OpenMAIC Documentation

Technical Documentation: THU-MAIC/OpenMAIC

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

🗞️ News Copy Chapter

• 2026-10-18 — v1.2.1: web research. Kimi, DeepSeek and Firecrawl join as web-search providers, and a new webFetch slot lets the agent read pages through a hosted reader (DeepSeek, Kimi or Firecrawl) instead of the built-in one; each is opt-in. Classroom chat can offer suggested replies, and retired models are removed from the built-in catalogs. Classroom chat now always runs on Pi and needs a classroom model with tool calling; read the release's Breaking Changes before upgrading.
• 2026-10-16 — v1.2.0: server-first is stable. Generation runs on the server and survives closed tabs and restarts, models are configured once in openmaic.yml (defaults, locks, and an option to forbid user keys), materials are parsed as soon as they are attached, and the web app and the API share one pipeline. New: classroom export, as a PPTX that keeps every scene or as one offline HTML file that plays the lesson. It needs PostgreSQL and a long-running server; Vercel deployments stay on 1.1.x. Read Upgrading from 1.1.x before upgrading.
• 2026-09-28 — v1.1.2: security — provider requests connect only to validated addresses and refuse redirects (GHSA-g87c-cm4q-cw5x).
• 2026-09-27 — v1.1.1: security — hardened MinerU Cloud parsing (GHSA-cpjc-vgjh-c5jp).
• 2026-09-24 — v1.1.0: agentic classroom chat (ask about any slide element, interactive, or whiteboard drawing); settings rebuilt around the course workflow; Token Plan connections.
• 2026-09-15 — v1.0.3: security — access-code tokens expire, render-service network policy, pinned audio connections, Next.js RCE patch.
• 2026-09-14 — v1.0.2: security — SSRF and DNS-rebinding fixes, classroom overwrite fix.
• 2026-09-06 — v1.0.1: security and stability; tightens two defaults.
• 2026-08-27 — v1.0.0: agent workbench, durable sessions, reusable skills, session materials, provider-neutral capabilities.

Earlier releases

• 2026-08-14 — v0.3.2: video export hardening, server-backed persistence and asset registry, @openmaic/generation, four new locales, FunASR.
• 2026-07-21 — v0.3.1: one-click MP4 export, direct slide editing, smarter "Edit with AI", expanded document parsing.
• 2026-06-28 — v0.3.0: PBL v2, "Edit with AI" editor agent, @openmaic/* SDKs on npm, relicensed to MIT.
• 2026-06-02 — v0.2.2: MAIC Editor Pro Mode, editable outlines, offline classroom export.
• 2026-04-26 — v0.2.1: VoxCPM2 TTS with voice cloning, per-model thinking config, course completion page.
• 2026-04-20 — v0.2.0: Deep Interactive Mode — 3D, simulations, games, mind maps, online programming.
• 2026-04-14 — v0.1.1: language inference, ACCESS_CODE, classroom ZIP export/import, Ollama.
• 2026-03-26 — v0.1.0: discussion TTS, immersive mode, keyboard shortcuts.

Full history in the changelog.

📖 Overview Copy Chapter

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.

https://github.com/user-attachments/assets/8f3f1e5f-1468-4e93-8054-afeeea683a61

Highlights Copy Section

• 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 — A .pptx that keeps every scene, one offline .html file that plays the whole lesson, or a classroom ZIP to move it to another deployment
• 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

🚀 Quick Start Copy Chapter

Prerequisites Copy Section

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

1. Clone & Install Copy Section

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

2. Configure Copy Section

cp .env.example .env.local            # API keys and server options
cp openmaic.example.yml openmaic.yml  # which models the server uses

The copied example needs only OPENAI_API_KEY in .env.local (or change its provider to one you have a key for); everything else in it is commented out until you want it. openmaic.yml declares providers (accounts the server can call) and gives each slot (a use of AI: the outline, slide content, text to speech, web search, …) a model. Keys stay in .env.local and are referenced as ${VAR}:

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}      # OPENAI_API_KEY=sk-... in .env.local
  anthropic:
    preset: anthropic
    apiKey: ${ANTHROPIC_API_KEY}

slots:
  llm: openai:gpt-5.5              # the default chat model
  course.outline: anthropic:claude-sonnet-4-6
  video: null                      # turn a capability off

The slots you write are the server's defaults; users can change them, or connect services of their own, in the app's model settings unless you lock them or set allowUserKeys: false. The server validates the file at startup and names every mistake by its field (or, for broken YAML, its line).

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, Lemonade and FunASR (local), and any OpenAI-compatible API.

[!TIP]
Recommended setup: OpenMAIC is at its best with every modality turned on — generated illustrations, narration, video clips, web search, and web fetch. A token plan configures the capabilities it supports with one key (see the examples below). Choose a fast long-context model such as deepseek-v4.1-flash as the default.

More examples: token plans, Xiaomi MiMo and GLM, Amazon Bedrock

MiniMax token plan quick example (one key for chat, image, video, TTS and web search; tokendance works the same way):

providers:
  minimax:
    preset: minimax
    apiKey: ${MINIMAX_API_KEY}

slots:
  llm: minimax:MiniMax-M3
  image: minimax                   # a provider id alone: the plan's default model
  video: minimax
  tts: minimax
  webSearch: minimax

TokenDance quick example with a fast long-context default model:

providers:
  tokendance:
    preset: tokendance
    apiKey: ${TOKENDANCE_API_KEY}

slots:
  llm: tokendance:deepseek-v4.1-flash
  image: tokendance
  video: tokendance
  tts: tokendance
  webSearch: tokendance

Xiaomi MiMo Token Plan and GLM (Zhipu) quick example:

providers:
  mimo:
    preset: xiaomi
    apiKey: ${MIMO_API_KEY}
    baseUrl: https://token-plan-cn.xiaomimimo.com/v1
  glm:
    preset: glm
    apiKey: ${GLM_API_KEY}
    baseUrl: https://open.bigmodel.cn/api/paas/v4   # or https://api.z.ai/api/paas/v4

slots:
  llm: mimo:mimo-v2.5-pro
  course.content: glm:glm-5.1

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

Amazon Bedrock quick example:

providers:
  bedrock:
    preset: bedrock
    models: [us.anthropic.claude-sonnet-5, us.anthropic.claude-opus-4-8]

slots:
  llm: bedrock:us.anthropic.claude-sonnet-5

Bedrock uses AWS environment credentials or the AWS SDK credential provider chain, with the region from BEDROCK_REGION (for example BEDROCK_REGION=us-east-1 in .env.local). 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.

3. Start the database Copy Section

pnpm db:up

Then uncomment the local DATABASE_URL line in .env.local:

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

pnpm db:up starts a development PostgreSQL on 127.0.0.1:5432 (set OPENMAIC_DB_PORT for another port). It is its own Compose project, openmaic-dev-db, shared by every checkout on this machine, with its own container and volume, so it never touches the database of a docker compose up stack. pnpm db:down stops it and keeps the data. Any other PostgreSQL works too.

4. Run Copy Section

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

5. Build for Production Copy Section

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

Keep the server running as a long-running process (a process manager or a
container): course generation runs inside it and continues after the browser
leaves the page. See the
Deployment guide for the required
configuration and for upgrading from 1.1.x.

Docker Deployment Copy Section

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. Courses, generated media and runtime sessions live in the named volumes openmaic-postgres and openmaic-data, which survive docker compose down and rebuilds; docker compose down -v deletes them. To configure models with openmaic.yml, create it from openmaic.example.yml and uncomment its mount in docker-compose.yml; otherwise connect a model service in the model settings once the app is running.

The Compose file is a personal installation: it runs in single-user mode (every browser sees one shared library) and listens on 127.0.0.1:3000 only. To serve other machines, protect it first:

1. Set a long random ACCESS_CODE in .env.local (details). Without it, anyone who can reach the port owns, edits and can delete the whole library.

2. Before the first start, set PERSISTENCE_POSTGRES_PASSWORD to a random value of letters and digits.

3. Publish on the network address:

   bash Copy

   OPENMAIC_PUBLISH_ADDRESS=0.0.0.0 docker compose up -d --build

OPENMAIC_PUBLISH_ADDRESS, OPENMAIC_PORT and PERSISTENCE_POSTGRES_PASSWORD come from your shell or a .env file next to docker-compose.yml, not from .env.local. Overriding the Compose defaults, rotating the database password and the full upgrade notes are in Hosting and identity.

[!IMPORTANT]
Upgrading a Compose deployment? PostgreSQL now always starts, the app is published on 127.0.0.1 only, and every visitor is the same single owner. If .env.local sets PERSISTENCE_SHARED_OWNER_ID, also set OWNER_SINGLE_USER=false, or the app refuses to start. Read Upgrading a Compose deployment first.

Slow-network / China build acceleration

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.

Vercel Deployment (up to 1.1.x) Copy Section

Serverless deployment is supported up to OpenMAIC 1.1.x. From 1.2.0, course
generation runs on the server in a process that outlives requests, so OpenMAIC
needs a long-running Node.js process with PostgreSQL (the
Docker deployment or pnpm start); Vercel and other
serverless hosts are not supported, and the repository no longer ships a
vercel.json. To deploy 1.1.x on Vercel:

1. Fork this repository on GitHub, unchecking Copy the main branch only.
2. In the fork, set the default branch to release/1.1.x (Settings → General → Default branch).
3. In Vercel, Add New → Project and import the fork. Vercel builds its default branch; configure at least one LLM provider key as described in that branch's .env.example.

Such a deployment can move to a long-running host later without losing data:
point the new host's DATABASE_URL at the database it used, if it used one,
and serve it at the same address, since browsers keep their data per site; the
courses visitors kept in their browsers are imported the first time each
browser opens the upgraded app. See
Upgrading from 1.1.x
for every kind of deployment.

Server-backed persistence (PostgreSQL) Copy Section

OpenMAIC keeps courses on the server. Course documents, folders, chat history, learner sessions and generated media live in PostgreSQL (media optionally in S3), served by the app itself at /api/persistence. The browser keeps only what belongs to the device, such as settings, playback position and caches; Settings → Clear Local Cache never touches the server.

• DATABASE_URL is required. Without it the server prints the fix and exits with code 1. Compose sets it for you; for development, pnpm db:up starts a database.
• Courses an older build kept in the browser are imported once per browser, automatically, the first time it opens the upgraded app. The browser copy is left untouched.
• Invalid settings stop the server at startup with a one-line [boot] reason instead of a server that answers every request with 500.

Who owns a course. Every request resolves to an owner, and each owner has its own library. Pick one identity mode:

Set the mode before the first start of 1.2.0: classrooms that 1.1.x saved as files are imported for the owner configured then. See Upgrading from 1.1.x for every kind of deployment.

Running OpenMAIC for other people, or embedding it in your own product? Hosting and identity covers:

• who can read and write stored data, and the removed PERSISTENCE_DEV_TOKEN;
• asset collection, quotas and S3 egress (ASSET_*);
• every startup check;
• owner identity: single-user mode, registering auth methods, a signed-JWT gateway recipe and claiming anonymous work;
• host extension hooks for course creation, the library, uploads and asset byte stores.

Optional: ACCESS_CODE (Shared Deployments) Copy Section

Protect a deployment with a site-level password in .env.local:

ACCESS_CODE=your-secret-code

Use a long random value, at least 16 characters from a random generator: it is the only secret guarding the deployment. Visitors then see a password prompt, and every API route is gated too. When it is unset (the default in .env.example), middleware.ts checks no credential and every route, the API included, is reachable: an unconfigured deployment is not gated, and there is no second enforcement point. The code is remembered for 7 days in a signed HTTP-only cookie; attempts are rate limited only behind a trusted proxy with TRUST_PROXY_HEADERS=true. See Configuration → ACCESS_CODE.

Optional: Agent workbench and runtime Copy Section

The Pro workbench, a course-building surface entered from the home page, is off by default. Turn on its build-time entry point and the server runtime; it uses the same PostgreSQL as the rest of the app:

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, which follows the default chat model unless assigned and needs a model with tool calling:

slots:
  llm: openai:gpt-5.5
  agent:
    model: openai:gpt-5.5
    api: openai-completions        # or openai-responses

The agent slot must not set thinking.effort. Its routes, the DEFAULT_MODEL caveat and runner tuning are in Hosting and identity.

Optional: Lemonade (Local AI Provider) Copy Section

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:

providers:
  lemonade:
    preset: lemonade
    baseUrl: http://localhost:13305/v1
  lemonade-tts:
    preset: lemonade-tts
    baseUrl: http://localhost:13305/v1
  lemonade-asr:
    preset: lemonade-asr
    baseUrl: http://localhost:13305/v1
  lemonade-image:
    preset: lemonade-image
    baseUrl: http://localhost:13305/v1

slots:
  llm: lemonade:Gemma-4-26B-A4B-it-GGUF
  tts: lemonade-tts
  asr: lemonade-asr
  image: lemonade-image

With the legacy variables, the same is LEMONADE_BASE_URL, TTS_LEMONADE_BASE_URL, ASR_LEMONADE_BASE_URL and IMAGE_LEMONADE_BASE_URL.

Optional: FunASR (Local Speech Recognition) Copy Section

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:

providers:
  funasr:
    preset: funasr-asr
    baseUrl: http://localhost:8000/v1

slots:
  asr: funasr

(Legacy variable: 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.

Optional: Local Audio and Video Extraction Copy Section

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 assign the asr slot (for example FunASR, Lemonade, or OpenAI) as 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.

Optional: MP4 Video Export (Render Service) Copy Section

The "Export Video" menu builds a self-contained Hyperframes 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:

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 for standalone setup and tuning (RENDER_MAX_CONCURRENCY, etc.). When upgrading, upgrade the render-service together with the app or before it: render jobs are bound to their owner, and a mix of old and new versions fails closed.

Optional: MinerU (Advanced Document Parsing) Copy Section

MinerU provides enhanced parsing for complex tables, formulas, and OCR. You can use the MinerU official API or self-host your own instance.

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.

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) Copy Section

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

See the VoxCPM repo 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:

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 Copy Chapter

Agent Workbench and Pro Mode (v1.0.0) Copy Section

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:

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 <CAP>__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 Copy Section

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!) Copy Section

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.

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.

Lesson Generation Copy Section

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:

Classroom Components Copy Section

| 🎓 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 Copy Section

| - 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 Copy Section

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

Just tell your agent assistant what you want to learn — it handles everything else:

• Hosted mode — Grab an access code from 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:

clawhub install openmaic

Configuration & details

Optional config in ~/.openclaw/openclaw.json:

{
  "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 Copy Section

See Exporting a classroom for the options, the ZIP that classrooms over 400 MB are saved as, and opening an exported file on a phone.

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 Copy Section

• 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 Copy Chapter

🤝 Contributing Copy Chapter

We welcome contributions from the community! Whether it's bug reports, feature ideas, or pull requests — every bit helps.

Project Structure Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Key Architecture Copy Section

• 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/chat/pi/) — Server-side Pi director loop that hands each classroom turn to agents through call_agent
• 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 Copy Section

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 Copy Chapter

This project is licensed under the MIT License, so commercial use is permitted free of charge. For partnership or collaboration inquiries, please contact: [email protected]

📝 Citation Copy Chapter

If you find OpenMAIC useful in your research, please consider citing:

@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 Copy Chapter

📄 License Copy Chapter

This project is licensed under the MIT License.

Third-Party Components Copy Section

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/pptxgenjs — MIT (third-party)

When redistributing the repository as a whole, the terms of each bundled package above apply to that package's files.

Packages Docs README (`packages/docs/README.md`) Copy Section

This is a Next.js application generated with
Create Fumadocs.

Run development server:

npm run dev
# or
pnpm dev
# or
yarn dev

The site is mounted under the /docs basePath, so open
http://localhost:3000/docs in your browser.

Build the static site (next build + static export, output in out/):

pnpm build

Explore Copy Chapter

In the project, you can see:

• lib/locales.mjs: Single source of truth for locales — language list, default
  locale, per-locale search tokenizer, RTL set, labels, and the /docs basePath.
  Plain JS so the scripts/postexport.mjs build step can import it too.
• lib/source.ts: Content source adapter, loader() wires the MDX content with i18n.
• lib/layout.shared.tsx: Shared layout options (nav, GitHub link, Live Demo link).

Fumadocs MDX Copy Section

A source.config.ts config file has been included, you can customise different options like frontmatter schema.

Read the Introduction for further details.

Known limitations Copy Chapter

English supports only top-level docs pages Copy Section

The default locale (en) is served unprefixed (/docs/getting-started). To keep
it unprefixed without the hydration conflict that a catch-all two-route-group
split causes, the English route app/(en)/[slug] is a single (non-catch-all)
segment. As a result, nested English pages would 404 — e.g.
content/docs/guides/intro.mdx resolves for every other locale (their routes are
catch-all under app/(intl)/[lang]/[...slug]) but not for English.

Only top-level English docs pages work today. Adding nested English docs requires
revisiting the (en) route group (and resolving the hydration conflict that the
current split avoids); this is deliberately deferred.

Learn More Copy Chapter

To learn more about Next.js and Fumadocs, take a look at the following
resources:

• Next.js Documentation - learn about Next.js
  features and API.
• Learn Next.js - an interactive Next.js tutorial.
• Fumadocs - learn about Fumadocs

Packages Docs Content Docs Getting Started (`packages/docs/content/docs/getting-started.mdx`) Copy Section

title: Getting started Copy Chapter

OpenMAIC is a Next.js application that runs on your own machine. You need to configure at least one LLM provider: cloud providers usually require an API key, while local Ollama or Lemonade does not.

Prerequisites Copy Chapter

• Node.js 22.19.0 or later
• pnpm 10.28.0 (if needed, run npm install [email protected])
• At least one LLM provider; cloud providers usually require an API key, while local Ollama or Lemonade does not

Install Copy Chapter

Clone the repository and install dependencies:

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

Installation builds the workspace packages required by the project, so the first install may take some time.

Configure Copy Chapter

Copy the example environment file and configure at least one LLM provider:

cp .env.example .env.local

Then configure a model. The simplest file setup is a minimal openmaic.yml next to .env.local, with the key in .env.local:

OPENAI_API_KEY=sk-...

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}

slots:
  llm: openai:gpt-5.5

openmaic.example.yml is this same starting point, with optional providers and slots commented out. Without the file, the legacy provider variables still work as long as DEFAULT_MODEL names the model:

ANTHROPIC_API_KEY=sk-ant-...
DEFAULT_MODEL=anthropic:claude-sonnet-4-6

To skip both, start the app and enter a plan's key in Settings → Token Plan, or a service's key in Settings → Model Services. Without openmaic.yml, DEFAULT_MODEL or a service set up there, no model is configured and generation fails.

See Configuration for complete provider, image/video generation, TTS, ASR, document parsing, web search, access control, and feature flag configuration.

Run Copy Chapter

Courses are stored in PostgreSQL, and the server refuses to start without DATABASE_URL. Start a local development database (a separate PostgreSQL in Docker on 127.0.0.1:5432, shared by every checkout on this machine; set OPENMAIC_DB_PORT for another port) and set DATABASE_URL in .env.local:

pnpm db:up

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

Start the development server:

pnpm dev

Open http://localhost:3000. You should see the OpenMAIC classroom generator. Enter a topic or upload learning material, then click Generate; the AI teachers will build a complete, multi-scene classroom. Supported material formats depend on the selected parser and typically include PDF, Office documents, Markdown/plain text, images, and some audio/video formats. Consult the parser's supported formats for the exact range.

Export a classroom Copy Chapter

Once a classroom and its media have finished generating, the download button at the top right of the classroom opens the export menu:

• Export PPTX: editable slides. With placeholder slides (recommended) keeps interactive, quiz and project-based learning scenes where they are in the lesson, each as a slide with an Open online button and a QR code that open the scene in the online classroom. Slides only leaves those scenes out.
• Export Resource Pack: the same PPTX choice, plus each interactive scene as a self-contained web page.
• Export as HTML: one self-contained file that plays the classroom without a network connection, with narration and captions, spotlight and laser, slide video, discussion cards and interactive scenes. Quiz, interactive and project scenes wait until the learner moves on. A project-based learning scene keeps only its briefing (goal and milestones); continuing the project needs the online classroom and a network connection. If the export reports assets it couldn't bundle, those parts of interactive scenes don't show in the offline HTML; they are still available in the online classroom. With narration and video plays like the classroom; Without narration makes a smaller file that paces the captions by reading time and leaves videos out.
• Export Classroom ZIP: the course structure and media, to back the classroom up or import it on another OpenMAIC deployment.

A classroom that would exceed 400 MB as one HTML file is saved as a ZIP instead: extract the whole ZIP and open classroom.html, keeping the audio/, media/ and images/ folders next to it.

The exported HTML file needs a web browser with JavaScript. On a phone, open it in a browser such as Safari or Chrome: on iPhone it does not play inside WeChat or the Files preview.

Build for production Copy Chapter

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

Or deploy with Docker or on your own server—see the Deployment guide.

Next steps Copy Chapter

• Configure providers, TTS, and ACCESS_CODE →
• Deploy with Docker or on your own server →
• For architecture details or contribution guidance, visit GitHub

Packages @Openmaic Storage Docs Asset Http Contract (`packages/@openmaic/storage/docs/asset-http-contract.md`) Copy Section

Asset registry HTTP contract

This contract exposes the asset operations — put / identify / resolve / remove / replace — over HTTP. All paths below are relative to a deployment-defined base URL. Path segments are percent-encoded UTF-8 strings. Metadata travels as JSON; asset bytes travel as bytes, as a multipart part on writes and as the whole body on reads. Successful operations with no return value respond with 204 No Content.

The server backend for this contract ships as createAssetHttpHandler, with asset requests dispatched by createStorageHttpHandler. The conformance server this package provides remains test-only: it implements no authentication or authorization model beyond what the contract's response codes require, because deriving the principal from an authenticated session is the reference server's job.

The design this contract serves has three layers — an allocated asset id names a registry entry, and a registry entry names a content hash, and a content hash names bytes. Only the first layer is on the wire. The content hash is an internal deduplication key: it MUST NOT appear in any URL, response header, response body, error message, error details, or log line.

That prohibition is not satisfied by omitting the hash itself. Bytes are shared across principals and their storage row has no owner, so no response header, body value, or status may be derived from the blob row except the representation's byte length. Every other value on a byte response comes from the registry entry — its media type, its revision, its own creation time. The byte length is allowed because it is an inherent property of the representation and is the same value a GET obtains from the returned bytes; retaining it in the registry lets HEAD reproduce Content-Length without fetching those bytes. Last-Modified is the trap worth naming: sourced from the shared row's creation time, as a static-file idiom naturally would, it reports a timestamp earlier than the caller's own write and thereby proves another principal stored those bytes first. Byte responses MUST NOT carry Last-Modified, Age, or any other value read from the shared row; note that the no-store requirement below already makes Last-Modified pointless. Frameworks that generate ETag and Last-Modified by default MUST have both disabled on these routes.

The hash MUST be a collision-resistant digest of at least SHA-256 strength, untruncated. This is a security requirement rather than an implementation preference, and it is the unstated precondition of two rules below: a server writes bytes unconditionally, so under a colliding digest one principal's write silently substitutes the bytes every other principal's entries resolve to — and an object-storage byte layer names each object by that digest, so a collision there is a cross-principal overwrite at the storage layer as well.

An asset id is opaque and unconstrained Copy Chapter

An asset id is a string this package allocated, but nothing in this contract may depend on its shape. Ids are compared, never parsed. There is no id validator that can reject an id on either side, and a server MUST NOT refuse one for its content. (The client does inspect an id for the three transport classes below, but only ever to answer "miss" locally — never to reject.)

The consequence is the one that matters: an id this registry never allocated is a miss, not an error. An id from another id space, an empty string, a string containing NUL, four kilobytes of padding, ../../etc/passwd — each is an ordinary lookup that finds nothing. This is not leniency. An id whose shape could be rejected would answer a question the caller is not entitled to ask, and a caller who can distinguish "malformed" from "not yours" has learned something about the id space. The browser backend documents this rule for the same reason, and the shared conformance suite pins each case.

A server therefore stores and looks up the decoded id as an opaque value — a bound query parameter, or a derived constrained storage id — never as a path component, a filename, or an unescaped fragment of a query. An id like a/../../b, arriving percent-encoded as a%2F..%2F..%2Fb, is one opaque lookup that traverses nothing.

Ids that cannot be a path segment Copy Section

Validity is a property of the id; reachability is a property of the transport. An id sits mid-path here, before the trailing content segment, and three classes of id cannot be carried there:

1. An unpaired UTF-16 surrogate has no percent-encoding; encodeURIComponent throws.
2. A whole-id . or .. is normalized away by URL path parsing before the request is sent, so /assets/../content would address /content.
3. The empty id collapses /assets//content, which intermediaries that merge slashes rewrite to /assets/content.

The third has no counterpart in the KVStore HTTP contract, whose key is a trailing segment and round-trips when empty. The danger in all three is identical and it is not that the request fails — it is that the request succeeds against something else.

The client MUST therefore resolve these three locally, before building any request. It does not raise an error: it answers as a miss — resolve returns null, remove succeeds as a no-op, and replace fails as it does for any id the registry does not hold, with a synthesized ASSET_NOT_FOUND since there is no response to reconstitute one from. This is where this contract deliberately diverges from KV, which refuses an unencodable key with a client-side KEY_NOT_ENCODABLE. Throwing would be wrong here: an unknown id is a miss by the rule above, the shared conformance suite pins the empty string as a miss on both resolve and remove, and a client that threw would both fail that suite and reintroduce the shape oracle the rule exists to prevent. The distinction to preserve is not loud-versus-quiet; it is that the id must never address something it does not name.

Note that ids which merely look structural need none of this. ../../etc/passwd percent-encodes to ..%2F..%2Fetc%2Fpasswd, one ordinary segment that reaches the server and misses there; it illustrates the id-domain rule, not the local-resolution one.

Transport hazards a deployment owns Copy Section

Beyond those three, the path carries an id through intermediaries that may refuse or rewrite it, and the shared suite pins ids in each category. A conforming deployment MUST pass the id segment through unmodified, and MUST verify that it does:

• A percent-encoded NUL (%00) is rejected outright by some servers and filters.
• A percent-encoded slash (%2F) is rejected or normalized by servers that do not allow encoded slashes by default — which the bucket/path/to/object.png shape produces.
• A very long id may exceed a request-target ceiling and be refused with 431 before routing. No length is invalid; a long id is simply not reachable past that bound.

Each of these turns a pinned miss into a thrown error, and none is predictable client-side, so none may be papered over by mapping an unclassifiable 4xx to a miss — that would break the rule that only a specific code becomes a miss. They are deployment configuration, and the shared suite's cases stand as the acceptance test for it. Real ids, being allocated by this package, encounter none of them.

Endpoints Copy Chapter

The route table admits exactly one segment after assets, and it is the id. There is no principal segment and no digest segment to supply, so any other path shape is 404 ROUTE_NOT_FOUND — a routing outcome that requires inspecting nothing. A path that does match a table entry but with a method that entry does not list is 405 METHOD_NOT_ALLOWED, carrying an Allow header naming that route's methods; since route matching never consults the registry, neither outcome discloses anything about an id.

No route takes a query parameter. A server MUST reject any request whose target contains ? at all with 400 VALIDATION_FAILED — stated on the raw target rather than on a parsed query, so that a bare trailing ? cannot be read as absent by one implementation and present by another. That is total where an enumeration of forbidden parameter names would not be, and it costs nothing, because there is no parameter here to preserve.

There is deliberately no metadata read route. No backend offers one: the browser store's public surface is put / resolve / invalidate / release / replace / remove / close, and no metadata member is ever returned to a caller. (contentType is read back, but only by the store itself, to label the bytes it hands out.) A route no backend can satisfy is not a contract but a promise. Warm-cache revalidation is what HEAD is for.

HEAD performs an ownership-checked registry identity read and MUST NOT read or materialize the asset bytes. Its status and headers are identical to GET for the same registry state; only the response body is absent. The registry's recorded byte length supplies Content-Length, so reproducing the GET headers does not require a byte-layer read.

Read routes MUST be served with Cache-Control: private, no-store and Vary: Cookie, Authorization, and MUST NOT be cached by any intermediary; the client sends its reads with cache: 'no-store' for the same reason, since a UA cache serving a stale 200 would defeat revision revalidation invisibly. Note that this differs from a content-addressed design, where bytes named by their digest never change and are safe to cache forever: here replace mutates the bytes behind a stable id, so no HTTP cache may serve a response for an id without revalidating. The client's own snapshot cache is a different thing and is governed below.

Byte responses MUST NOT advertise Accept-Ranges and MUST ignore a Range header, always answering 200 with the complete representation. A 206 would carry a response model this contract does not define, on a route whose headers are load-bearing for revalidation.

Transport: bytes and metadata Copy Chapter

POST /assets and PUT /assets/{id}/content take multipart/form-data, with the parts in this order:

• meta — application/json, the metadata object. Required on POST. Optional on PUT, where its absence is meaningful; see below.
• bytes — the asset bytes, carrying the asset's own Content-Type. The package client uses application/octet-stream when the source blob has no type, because multipart parsers otherwise supply their own default media type.

The multipart framing MUST be parsed by a standards-conforming multipart parser; a deployment MUST NOT hand-roll one. A bespoke grammar disagrees with the parsers intermediaries use, and every such disagreement is a way for a scanner and the application to see different parts.

Both parts MUST carry a filename. Without one, a conforming parser returns the part as a string, discards its headers, and text-decodes its payload, silently replacing invalid UTF-8. Each filename is fixed by the package client, never read by this package, and never derived from caller data. Preserving meta as a file allows the server to require its Content-Type to be application/json and to decode its bytes as UTF-8 with errors reported rather than replacement characters inserted.

Multipart rather than metadata alongside a raw body, because there is nowhere safe to put the metadata. It is an open-ended object, and real callers fill it with generated-narration text and image-generation prompts — unbounded caller-supplied content. In a query parameter that content would sit in the request target, where it hits the request-target ceiling and is written verbatim into every intermediary's access log. A custom header has the same size problem for the same reason. Multipart is a standards-defined framing rather than a bespoke one, which is the property that matters; maxMetaBytes must be enforced against the parsed metadata part before the JSON is parsed rather than after.

From this, one rule the other layers have no need for:

Metadata is unbounded caller-supplied content. It MUST NOT appear in any URL, response header, response body, log line, error message, or error details. The single exception is contentType, which determines a byte response's Content-Type as specified below. In particular a Content-Disposition filename MUST NOT be derived from metadata: it would put caller content in a header, and an unescaped one is a header-injection primitive. Use a fixed name or the id.

The client's request-header hook MUST NOT set Content-Type, and a client whose hook does MUST fail loud rather than choose a winner. Under multipart this is more serious than mislabelling: overwriting Content-Type destroys the boundary parameter, and every write from that deployment fails to parse with an error naming nothing an operator can act on.

Sizes Copy Section

Three byte limits and one part-count limit, because they bound different things:

Only maxRequestBytes is enforced before multipart parsing. It bounds the raw body read from the wire and is therefore the only ceiling on parser work and request-derived memory. The platform's Response.formData() then materializes every part before maxParts, maxMetaBytes, and maxAssetBytes are checked on the parsed result; those three limits bound what the handler accepts, not what the multipart parser processes.

This trade is deliberate. A streaming multipart parser with its own limits would introduce a second grammar that could disagree with the standards-conforming platform parser, recreating the scanner/application parser differential this delegation exists to remove. Bounded memory is preserved by maxRequestBytes; maxParts, maxMetaBytes, and maxAssetBytes remain finer-grained admission rules for the parsed request. Separate asset and metadata limits are still necessary because one shared admission limit either caps assets at metadata scale or admits metadata at asset scale. Per-part header bounding belongs to the standards-conforming parser rather than to this contract.

The outer bound is measured differently from the inner two, and deliberately so: it exists to stop reading, so it cannot wait for a decode. A handler MUST assert at construction that maxRequestBytes exceeds maxAssetBytes + maxMetaBytes with room for multipart framing, or the outer bound silently masks the inner one — with the defaults above equal, an asset at exactly maxAssetBytes would always be rejected by the request bound, reporting the wrong limit.

None may be inferred from Content-Length, which is a claim by the sender. Counting bytes as they are read is necessary but not sufficient for the decoded limits — under a Content-Encoding the bytes read are a fraction of the bytes stored, and the expansion lands inside the transaction that holds the write. A server therefore MUST reject Content-Encoding on these requests with 400 VALIDATION_FAILED. Exceeding any size limit is 413 PAYLOAD_TOO_LARGE, raised before any bytes are stored.

Malformed and hostile bodies Copy Section

A request whose Content-Type is not multipart/form-data is 415 UNSUPPORTED_MEDIA_TYPE. A failure by the multipart parser, including invalid boundary framing, is 400 VALIDATION_FAILED with a fixed package message. The expected entries are exactly meta and bytes on POST, and bytes with optional meta on PUT; any other entry name or any duplicate is 400 VALIDATION_FAILED. Duplicate entries in particular MUST be rejected rather than resolved by a first-wins or last-wins rule: a scanning intermediary and the application choosing differently is a parser differential, and the two would disagree about which metadata a request carried.

When both entries are present, meta MUST precede bytes.

Recording the media type Copy Section

On POST, the recorded media type is meta.contentType when that member is present — including when it is the empty string — and the bytes part's own Content-Type only when it is absent. The distinction is ?? rather than ||, and it is observable: an explicitly empty contentType records the empty string and is therefore served as an attachment, where a fallback would have served the blob's type inline.

On PUT, when meta is present it replaces the entry's metadata wholesale and the media type is derived the same way. When meta is absent, the entry's existing metadata is retained and its media type is retained unless the bytes part carries one.

The package client always carries a media type on bytes: an untyped source blob is sent as application/octet-stream. This is necessary because a standards-conforming parser supplies a default media type for a file part whose header omits one, so omission cannot survive parsing as an empty type and cannot signal retention. Metadata omission still retains the existing metadata object; only the media type follows the replacement bytes.

The two branches are metadata present versus metadata absent, matching the browser backend's metadata replacement and retention behavior. The absent branch is the one that matters: regenerating bytes in place while keeping the recorded provenance is the use case replace exists for. A wire on which meta were mandatory would force a client to send {}, erasing the accumulated prompt, model, narration, and voice on every regeneration — through a call that returns 204.

Media-type retention is a deliberate divergence. The browser backend can retain the existing media type when metadata is absent and the replacement blob is untyped. The HTTP path cannot reproduce that behavior because a conforming multipart parser supplies a default type for a file part whose header omits one. The package client therefore sends application/octet-stream for an untyped replacement, and that type replaces the recorded media type even while the existing metadata object is retained.

Serving bytes Copy Section

Every response carrying bytes MUST send X-Content-Type-Options: nosniff and MUST serve a Content-Type from a renderable allowlist. The default allowlist is:

image/png  image/jpeg  image/gif  image/webp  image/avif
audio/mpeg  audio/mp4  audio/ogg  audio/wav  audio/webm
video/mp4  video/webm  video/ogg

Matching is exact, case-insensitive, and whole-string, with no parameters accepted. A deployment may narrow this list; widening it is a decision about executable content. Excluded, and MUST remain excluded: image/svg+xml and image/svg, text/html, application/xhtml+xml, text/xml and application/xml, and application/pdf. These are document formats that execute script, not media, and serving one same-origin turns stored bytes into stored script.

A recorded media type that is not a string, is empty, or is outside the allowlist is served as application/octet-stream with Content-Disposition: attachment. The empty case is real when metadata explicitly carries an empty contentType. The client MUST label its minted object URL from the served Content-Type and from nothing else; labelling it from metadata would reintroduce inside a blob: URL exactly what the allowlist excludes.

Relabelling is not refusal. resolve returns a minted URL for every stored asset regardless of media type; a non-renderable asset yields a URL labelled application/octet-stream that a media element will not render, and that is the intended outcome rather than a miss. Returning null instead would fail the shared conformance suite, every blob in which is text/plain — outside any sensible allowlist — and would conflate "these bytes are not safe to render inline" with "there are no bytes." The disposition header governs direct navigation and does no work on this path, where bytes reach the caller through fetch; the protection that carries the weight is the relabelling together with nosniff.

The three-layer design improves on a content-addressed one here, and it is worth stating why. Where bytes are shared across principals and the recorded media type travels with the bytes, one principal's metadata can determine how another principal's response is labelled — a stored cross-principal typing attack. Here the media type lives on the registry entry, and every entry belongs to exactly one principal, so a principal can only mislabel their own bytes. The attack is unrepresentable rather than mitigated, given the collision-resistant digest required above and the rule that no response value derives from the shared row.

`X-Asset-Revision` Copy Section

GET and HEAD on /assets/{id}/content, and the success responses of POST /assets and PUT /assets/{id}/content, MUST carry an X-Asset-Revision header: a monotonically increasing integer on the registry entry, starting at 1 and incremented by each replace. It is opaque to the client except for equality comparison.

It MUST NOT be derived from the content in any way. A content-derived validator — the reflex choice, and what an ETag from a static file server or object store would be — is the content hash under a different header name, and would disclose byte equality across ids to anyone holding two of them. Byte responses MUST NOT carry a content-derived ETag for the same reason.

Carrying it on the write responses too means a client learns the revision it produced without a second request, which would otherwise race a concurrent replace.

The headers and the body of a GET byte response MUST be produced from one transactionally coordinated read. Reading the revision and media type, releasing the transaction, and then reading the bytes lets a concurrent replace pair revision n headers with revision n+1 bytes, which the client then caches as authoritative. The browser backend closes the same window deliberately, reading the registry entry in the same transaction as the bytes. HEAD reads only the registry identity and recorded byte length in one ownership-checked query.

Resolution yields a client-minted object URL Copy Chapter

resolve returns a URL the caller can use as an `` / <audio> / <video> source. Over this contract, the client fetches the bytes through its own authenticated request and mints a local object URL from them. The server exposes bytes; it does not hand out a URL for a media element to load.

This supersedes the earlier resolution that a server-backed deployment would resolve to a self-hosted proxy path by default. That shape does not survive contact with how a resolved URL is consumed. A media element sends only ambient credentials — it cannot carry a client's request-header hook — so a proxy path works for deployments whose sessions are cookie-based and silently fails for header-authenticated ones. Closing that gap requires the deployment to mint and verify short-lived URL tokens, which is a second credential form invented inside a storage library and offered as the default.

Fetching the bytes through the client's ordinary authenticated request path needs no second credential form. It also preserves the browser backend's semantics, which is what lets consumers written against that backend keep working — but only if the client observes the rules below, which are the substance of that claim rather than a consequence of it. And it removes a class of disclosure surface: the client never receives a URL into which a hash could be embedded, so content-derived validators, cache keys, and URL shapes stop being questions this contract has to get right.

The cost, stated plainly: there are no range requests and no progressive playback. The bytes are downloaded in full before a media element sees them, and a resolved asset is held in memory until released — on the server side too, since a byte read materializes the asset rather than streaming it. This is what the browser backend already does, so it is not a regression for any existing consumer, but it is a real ceiling on large media. Self-hosted proxy paths and signed object-storage URLs remain possible later shapes; they are additive, and adding one when a deployment needs it beats defaulting to a shape that works for only half of them. Signed object-storage URLs have since landed as exactly such an additive, opt-in shape; see Indirect byte egress below.

Client resolution semantics Copy Section

These are normative. Two of them the shared conformance suite already pins; the rest it cannot, and saying which is which matters, because an implementer will otherwise trust a green suite to have checked them.

Pinned by the shared suite:

• Concurrent resolve calls for one id coalesce onto a single request and a single minted URL. Minting twice orphans one of them — nothing can revoke it — and pins the asset in memory twice.
• A remove invalidates the warm snapshot, and a resolve that misses retires it.

Normative but not pinned by the shared suite, and therefore the HTTP backend's own tests must pin them when it lands:

• A returned URL is an immutable snapshot. A later mutation retires it rather than revoking it; already-issued URLs stay valid. Only release(id) and close() revoke. (The suite has no release coverage; the browser backend's own tests carry it.)
• invalidate(id) is a local cache operation, distinct from release(id). It advances the id's resolution generation, prevents an older in-flight request from satisfying later callers, forgets the warm identity, and retires the current snapshot without revoking URLs already issued to holders. A replacement notification from another realm must invalidate before it resolves again.
• The object-URL cache is keyed per asset id, never per content. A client that keys it on a digest of the response bytes discloses byte equality to a holder of two ids — the disclosure the whole design exists to prevent, reintroduced client-side. The suite asserts identical bytes yield distinct ids, never that they yield distinct URLs.
• A replace invalidates the warm snapshot and any in-flight resolution for that id. (A put allocates a fresh id, which by construction has no cache entry to invalidate.)
• The warm-hit identity is the revision together with the served media type — the HTTP analogue of the browser backend's content-hash-and-media-type pair. The suite is transport-agnostic and has no vocabulary for revisions.
• A client records the revision carried by the response that delivered the bytes, never one learned from a HEAD. A HEAD decides only whether to re-fetch. Recording the HEAD's revision against bytes fetched afterwards labels revision n+1 bytes as revision n, and every later HEAD then confirms them as fresh.

One limit of this design is worth stating rather than leaving to be discovered: a replace performed elsewhere — another tab, another device — leaves a warm snapshot stale until the next revalidation, where the browser backend re-reads the registry inside every resolve. That is inherent to a network backend, and it is the one place these rules do not reproduce the browser's semantics.

Cross-origin deployments Copy Section

The client reads non-safelisted response headers on both reads and writes. A cross-origin server MUST send Access-Control-Expose-Headers: X-Asset-Revision, X-Error-Code on GET and HEAD, error responses included, and MUST expose X-Asset-Revision on the 201 success response from POST and the 204 success response from PUT. Without the read revision, the client's cache either never validates or validates as always-fresh. Without the error code, a client cannot classify any HEAD error and falls back to a full byte GET on every miss — so the mechanism HEAD exists to provide stops working, silently, in exactly the deployment shape this section addresses. Without the write revision, the client reports a committed allocation or replacement as a malformed response; retrying the non-idempotent POST then allocates a second entry for the same bytes.

A client accepts a credentials option and passes it through untouched. A credentialed cross-origin deployment answers with a concrete origin and Access-Control-Allow-Credentials: true, never *.

Indirect byte egress (deployment opt-in) Copy Section

Everything so far describes direct egress: a byte GET is answered 200 with the bytes materialized in the response body. A deployment MAY instead opt into indirect egress, under which a byte GET is answered with a short-lived signed URL for the object rather than the bytes — as a 302 Found with a Location for a generic consumer, or as a JSON descriptor for a client that asks for one, as specified below — when, and only when, the byte layer can sign. This is the signed object-storage shape anticipated above, and it is additive in the precise sense that a deployment which never opts in cannot tell it exists: off by default, and byte-for-byte unchanged when off. Only the byte GET changes shape; HEAD, writes, and remove are always answered directly, so X-Asset-Revision revalidation through HEAD works exactly as under direct egress.

Indirect egress is a preference, not a guarantee. A byte layer that cannot sign — the byte column in the transactional store cannot — answers 200 with the bytes even when the deployment opted in, and a client MUST therefore handle both shapes on the same route.

The rules that make the redirect shape safe are these, and an implementation MUST honor every one:

• Authorization is unchanged and still per-read. The 302 is minted only after the same checks the direct read performs — the deployment policy hook and the per-principal ownership check, in the same coordinated read — and a miss is still 404 ASSET_NOT_FOUND, indistinguishable from the direct path. The redirect changes who serves the bytes, never who may ask.
• A miss stays a miss wherever it surfaces. A registry miss is answered 404 ASSET_NOT_FOUND as it always was. Indirect egress adds one miss that arrives later: an entry owned and readable when the URL was minted, whose bytes are reclaimed before the client fetches it, which the object store answers 404. A conforming client MUST report that as ASSET_NOT_FOUND rather than as a malformed response — and only a 404 the store confirms as a miss: S3 and MinIO answer object errors with an XML body whose <Code> names the condition, so a client MUST treat exactly a declared NoSuchKey as the absent object and every other 404 (a wrong bucket, access point, or endpoint, under which the bytes still exist) as a malformed response. It is the same physical state the direct path reports as a miss, since the byte layer's own contract calls an absent object a miss and not an error, and what a read means must not depend on a deployment's egress setting. Signing MUST NOT probe for the object to close this window instead: the caller has already done the ownership-checked registry read, and an existence probe would both cost the round trip indirect egress exists to remove and make the mint's price vary with prior presence. This does put one requirement on the byte layer: an absent object MUST answer 404. S3 answers 404 NoSuchKey only when the signing identity holds s3:ListBucket on the bucket; without it a missing key answers 403, which no client can tell from a real credential fault, and the miss degrades to a malformed response. Grant it.
• The signed URL is short-lived. Its signature is the credential, so possession of the URL serves the bytes to anyone for its whole lifetime: indirect egress converts a per-read authorized response into a bearer token with a fuse. The fuse is seconds, not minutes. It MUST also sit far below the byte reclamation grace period, so bytes referenced when the URL was minted cannot be collected while the URL is still usable. The packaged handler enforces that rather than documenting it: enabling indirect egress requires declaring the reclamation grace the deployment runs its collector with, and construction fails for any lifetime above a tenth of that grace, or above the handler's own fifteen-minute ceiling. The grace has no default here, deliberately. A default would be a guess about a component the handler does not own, and a guess is what turns this invariant into something a deployment can hold wrongly while every individual setting looks reasonable. The "an asset id is not a capability" rule survives precisely because the capability the redirect introduces expires.
• The contract's response headers survive the redirect because they are pinned into the signature, not because the client re-derives them: the served media type after the renderable allowlist, the fixed attachment disposition for a non-renderable type, and the private, no-store cache posture. Object stores support exactly this as signed response-header overrides (response-content-type, response-content-disposition, response-cache-control); a byte layer that cannot pin them has no signing capability, whatever else it can sign. One header does not survive, and the design accounts for it: X-Content-Type-Options: nosniff is not among the overridable response headers, so the object store's answer lacks it. That is safe precisely because of the consumption model — the packaged client fetches the bytes and mints a typed blob: URL, so no media element or navigation ever sniffs the signed response's type; the allowlist relabeling has already decided what the bytes claim to be. A consumer that navigates to a signed URL directly gets no nosniff protection, which is one more reason the descriptor path is the one conforming clients use.
• The 302 itself carries X-Asset-Revision, Cache-Control: private, no-store, and Vary: Cookie, Authorization, Accept — the read route's posture, since the redirect is as per-principal as the bytes it points at. A client whose fetch follows redirects opaquely observes only the final response's pinned headers, which is one reason the packaged client asks for the descriptor below rather than follow.
• Cross-origin deployments own one more configuration. The byte fetch now crosses to the object store's origin, so that origin's CORS must admit the application origin and expose Content-Type. A deployment that skips this fails loud on the first read rather than silently.

What a conforming client does about the hidden 302 headers. Following a redirect is not neutral for it: the platform fetch forwards the original request's headers to the object store's origin — only Authorization is stripped across origins — so a deployment whose credential travels in a custom header would hand that credential to the object store, and the cross-origin preflight the forwarded custom headers provoke commonly fails there besides. A client therefore asks for the descriptor instead, and it asks through Accept: application/vnd.openmaic.asset-descriptor+json — a CORS-safelisted header, so the negotiation never turns a byte GET into a preflighted request, which a custom request header would. A redirect-egress server answers 200 with a JSON body {"url": ..., "revision": ...} under that same vendor media type as Content-Type, with the read route's cache posture and never a Location; the media type is what identifies the shape, so a stored asset can never parse as a descriptor — and to keep that true the type is reserved: a server MUST reject it in its renderable allowlist, since only the allowlist can put a recorded media type on the wire. The client then fetches the signed URL itself, with no deployment headers at all, takes the revision from the descriptor and the served media type from the byte response, and is otherwise unchanged: warm reads still revalidate through HEAD, which is never answered indirectly. A server that never redirects ignores the Accept and answers bytes exactly as before, so one client build serves both deployment shapes. The 302 remains the answer for generic HTTP consumers that did not ask for the descriptor; what they do with their own headers is their own affair.

The disclosure tradeoff, stated plainly. This contract forbids the content hash on the wire because it discloses byte equality across ids. The byte layers that ship key each object by that hash, so a Location into such a layer names the content hash, and a holder of two ids can compare the URLs they were redirected to and learn whether the bytes match — the disclosure the three-layer design exists to prevent, reintroduced at the egress point. Enabling indirect egress with a hash-keyed byte layer is therefore a deliberate deployment tradeoff, acceptable where byte equality across ids is not sensitive: public generated media is the motivating case, where payloads are large, visibility is already unrestricted, and moving the download off the application server is worth real cost. A deployment that needs the no-disclosure property MUST keep direct egress. A byte layer that keyed objects per registry entry rather than per hash would restore the property under indirect egress; none ships today.

The same tradeoff has a second, sharper edge that deployments should opt into with open eyes. An object store's GET response carries headers the signature cannot remove — ETag and Last-Modified among them — and the signed response-header overrides add but never strip. ETag is content-derived, so it sits in the same disclosure class as the hash in the URL. Last-Modified does not: because a deduplicated PUT rewrites the hash-keyed object, the header moves when another principal re-uploads the same bytes, and a holder of a signed URL who re-fetches it can observe shared-object write timing — who else wrote these bytes, and when. That is more than byte equality, and no shipped signer can suppress it. A deployment for whom that signal is sensitive MUST keep direct egress; a byte layer that never rewrote an existing object (or keyed objects per entry) would not expose it, and none ships today.

Allocation discloses nothing Copy Chapter

Every successful POST /assets allocates a new id, including for bytes the registry already holds. Returning an existing id would let any caller test whether arbitrary bytes are already stored — an existence oracle over data the caller never stored, and the reason the three-layer design exists at all.

The requirement is stronger than the return value. Every branch taken and every value returned on the success path MUST be independent of whether the bytes were already present. A server MUST NOT read-then-write: it writes the blob unconditionally and inserts the registry entry, so both paths execute the same statements in the same order.

The pending/committed distinction is equally unobservable. A pending entry resolves, HEADs, replaces and removes exactly as a committed one does; no route reads it, no error mentions it, and no response varies with it. That follows from where it is written rather than from care taken on each route: allocation always writes the same columns, and commit is a side effect of a document write, so no asset request ever decides anything on it.

Whether an entry is still referenced is a different matter, and there is exactly one intentional branch on it: the quota bullet below, which accounts live logical bytes and therefore reads that state on POST and PUT. A caller near its quota can observe that a write it makes succeeds after a document write releases an earlier entry. That is the same channel the quota bullet already documents — a deployment-configured limit whose whole purpose is to vary with what the principal holds — and it is listed there rather than claimed away here.

Three channels stay outside the guarantee, and a deployment MUST budget for them:

• Quota and metering. These MUST be accounted on the principal's logical bytes — the sum of the bytes referenced by that principal's live entries, live meaning every entry not yet marked unreferenced — and never on bytes physically newly written. Pending entries count whether or not their expiry has passed, because only the collector removes them; a quota that keeps counting an expired entry for one collection interval refuses a write slightly early, which is the harmless direction, where the opposite would admit one it should not. Counting entries that lost their last reference would make a quota a countdown rather than a ceiling: a regeneration would spend its predecessor's bytes forever instead of until the collector's grace period passes. Physical headroom above the sum of logical quotas remains the deployment's obligation, and the live-entry rule adds one term to it: an entry that has lost its last reference is outside the sum, so replacing its bytes cannot move the sum either, and a caller replacing such an entry repeatedly writes physical bytes a logical quota does not bound. The bound is the grace period — the entry is released after it, and the blob pass then reclaims every generation of bytes it named — so the headroom a deployment needs is its grace period times its peak replace rate. Refusing a replace on such an entry would be the tighter answer and is deliberately not taken: it would make an entry's lifecycle state observable on a write route, which the rest of this section exists to prevent. Under physical accounting a deduplicated write costs nothing while a fresh write costs quota, so two equally sized writes answer the oracle the rest of this design closes. The same applies to any storage estimate or billing readout. A deployment MUST also raise ASSET_QUOTA_EXCEEDED from the logical check before attempting a physical write, and MUST keep physical headroom above the sum of logical quotas — otherwise a write near capacity succeeds when the bytes deduplicate and fails when they are novel, and the filesystem answers the question the accounting rule closed.
• Cost, on the write path only. A deduplicated write does less physical work than a novel one, so POST and PUT latency and write volume vary with whether the bytes were already present. This contract does not promise constant-cost writes, and a deployment requiring that must provide it above this layer. Note that remove is not in this category: because reclamation is offline, it deletes one row and costs the same whether or not another principal holds the same bytes — a channel that a synchronous reclaimer would have left open. The reference-count value itself is unobservable in any response.
• Anything a deployment adds. A diagnostic, a storage estimate, or a rate-limit counter need not be read from the blob row to leak: it is enough that its value correlates with whether a write deduplicated. A deployment adding any such value to a response owes it the same analysis as the two channels above, over and beyond the blob-row rule, which closes only the values read directly from that row.

Where the bytes live Copy Chapter

The registry — ids, owners, media types, metadata, and the reference count — lives in a transactional store. The bytes are a pluggable layer behind it: a column in that same store, or a filesystem, or an object store addressed by content hash.

That is possible because of a decision made in the next section: reclamation is offline, never part of a request. Were a request allowed to delete bytes, a concurrent write deduplicating onto those same bytes could commit against them, and a byte layer outside the transaction would have no way to serialize the two — which is what would force bytes into the transactional store. Offline reclamation removes that race from every request path, and what remains is coordination on a row rather than on the bytes.

The invariant a byte layer must satisfy is therefore an ordering rule, not an atomicity one:

• The blob row is claimed first, in the transactional store, before the bytes are written. This is the step that serializes a write against the collector: claiming the row takes its lock, so a collector already holding it finishes first and the write then re-claims the row. Writing bytes before claiming would not be safe — the collector could delete them while the claim waited, leaving a fresh entry that points at nothing.
• Bytes are then written, before the entry that references them. A crash between the two leaves bytes nobody references, which costs storage and loses nothing; the reverse order would leave a registry entry pointing at bytes that were never stored.
• The write is unconditional. It must not be skipped because the bytes appear to be present already — partly because the interleaving above produces exactly that appearance, and partly because branching on prior presence is what the allocation rule forbids.
• Bytes are deleted after the last row referencing them, and only by the offline collector.
• The reference count and the decision to collect are serialized on that same blob row, which every byte layer keeps regardless of where the bytes themselves sit.

One consequence is worth stating rather than leaving to be discovered: byte-layer I/O happens while the registry transaction is open. The write path holds the blob row's write lock across the upload, and the read path holds a shared blob-row lock across the download so the collector cannot delete the object in flight. For a byte layer inside the registry store this costs nothing; for an object store it means a row lock and a database connection are held across network I/O, which is a consideration for how a deployment sizes maxAssetBytes and its connection pool. The read lock is shared, not exclusive, so concurrent reads of the same bytes do not serialize against one another.

Two implementations ship, and the interface exists because both are real rather than because one might be one day. A byte layer in the transactional store keeps bytes in a column: nothing to reconcile, since a rolled-back transaction leaves nothing behind, but its bytes flow through the write-ahead log and the backups, so backup and replication volume scales with stored assets — which is the reason to size maxAssetBytes deliberately, and eventually the reason to move off it. An object-storage byte layer keeps that volume out of the database at the cost of one housekeeping duty: the crash window above leaves unreferenced objects, so a deployment reconciles or expires them. Naming each object by its content hash keeps those orphans harmless — the next write of the same bytes overwrites one idempotently, so nothing has to hunt for them.

Reclamation is offline Copy Section

Bytes are shared across principals; a registry entry is not. remove deletes the registry entry and nothing else: it never reads, counts, or deletes bytes. Bytes outlive their last reference until a separate, offline collector takes them — one that finds byte rows with no references older than a grace period, locks each, re-checks, and deletes.

Three things follow, and each is a reason the design is this way rather than a consequence to tolerate:

1. Request paths never delete bytes. The write path claims the blob row before storing, and the read path holds a shared lock while reading bytes. The collector takes an exclusive lock before deletion, so it waits for in-flight reads and writes without serializing readers against one another.
2. A side channel closes. Were remove to reclaim, its cost would vary with whether another principal still held the same bytes, so a caller could learn that by deleting their own asset and timing it. A remove that only deletes one row costs the same either way.
3. Nothing is given up, because the guarantee never existed. With global deduplication, remove could never promise the bytes were destroyed — another principal referencing them keeps them. Synchronous deletion therefore bought far less than it appeared to.

The cost is real and belongs to the deployment: storage grows until the collector runs, and bytes a user deleted remain on disk until then. A deployment MUST configure the collector and its grace period; leaving both unset is a design that grows without bound. The retention posture that follows is the one deduplication already implied, now with a stated delay rather than an implied one.

The reference count spans all principals — that is what makes global deduplication reclaimable — and its value MUST NOT be observable in any response.

Collection is a host decision, not a contract event. A registry entry whose bytes are gone resolves to a miss rather than an error, because inventing an error would make collection observable.

Reference counting has a second level, from documents to asset ids, and a server implementing this contract MAY implement it. It is the same pattern one level up: an entry records when a document first named it and when the last document stopped naming it, and the same offline collector releases it after a grace period.

The second level has four parts:

1. A reference table. A row per (stage, scope, scene, asset id) the stored documents hold, maintained inside the document store's own write transactions, at the granularity those writes already have — a full save replaces a stage's rows, a scene write replaces that scene's, a delete removes them. The scope distinguishes a stage-level slot (stage whiteboards, the video manifest — which no scene owns) from a scene's own slots, and it MUST be a field of its own rather than a reserved scene id: scene ids are opaque and unvalidated, so a scene whose id matched any sentinel would otherwise share a key with the stage-level rows, and whichever scope was written second would delete the other's rows and mark its assets unreferenced. A slot value becomes a row only if the registry holds an entry under that id, established by a join in the same transaction. Nothing parses an id: placeholders, data: payloads, legacy URLs and ids from other id spaces produce no row and no error, which is the same rule that makes an unknown id a miss on every read.
2. Pending, then committed. A POST /assets allocates its entry with an expiry rather than a permanent claim, because the window between "the bytes were stored" and "a document names them" is bounded by nothing on the wire. The first document write that names the id commits the entry and retires the expiry, inside that write's transaction. There is no route for this and nothing on the wire changes: a client stores bytes, then writes the id into the document, exactly as before.
3. An entry pass in the collector, ahead of the byte pass and under the same batch cap and the same lock-and-re-check-per-row discipline. It releases entries that are pending and past their expiry, and entries whose last reference left longer ago than the grace period. Releasing one does what remove does: delete the row, and stamp the blob when no entry names those bytes any more — so the byte pass then reclaims them after its own grace, as designed.
4. A grace period rather than an instant. An entry that loses its last reference is stamped, not deleted. A deletion a user undoes, a document restored from an export, and the same id written back by a slower tab all land inside that window and simply clear the stamp again.

A deployment upgrading into this level has entries that predate it and documents with no rows. The collector walks the stored documents first, in bounded and resumable chunks, and may mark those entries committed only once that walk has covered every document — so an upgrade cannot release an entry the data it had not read still references. Each document is read inside the transaction that inserts its rows, and under a lock the document write paths take too, because reading outside it would let a concurrent save commit between the two and leave the walk inserting a reference that save had just removed.

The two halves are separately configured — a document store maintains the table, a collector releases entries — and a deployment that enables only the second deletes live media on the first expiry. A server MUST therefore record, in the registry's own storage, that a reference-maintaining document store has written, and its collector MUST refuse the entry level when that record is absent. An empty reference table cannot be told apart from documents that reference nothing; the absence of that record can. Refusing is not a warning: it is the difference between a misconfiguration that fails loudly on the first pass and one that is discovered when a user opens an old course.

Course deletion needs no separate path: deleting a document removes its rows and stamps the entries, and the next pass takes them after grace. DELETE /assets/{id} remains what it was, and a deployment that refuses it to its clients loses nothing by doing so.

Metadata domain Copy Chapter

Metadata is a JSON object whose one contract-relevant member is contentType; every other member is caller-defined and stored verbatim.

Because it travels through JSON, this backend accepts only plain JSON values that survive serialization without changing meaning. It MUST fail loud, before sending, on values such as Map, Set, Date, non-finite numbers, negative zero, nested undefined, bigint, sparse arrays, symbol-keyed properties, non-enumerable properties, strings containing U+0000, class instances, and circular references. U+2028 and U+2029 are valid JSON string contents and MUST be accepted.

This is a real capability reduction, not a tightening of a lossy path, and a deployment moving from the browser backend to a server one must audit its metadata against it. The browser backend persists a structured clone, which carries Date, Map, Set, ArrayBuffer, bigint, -0, and cycles faithfully, and throws only for what it genuinely cannot represent. So these values do not degrade quietly today; over this transport a put that works locally starts failing. (Structured clone does drop symbol-keyed and non-enumerable properties, so those two are lossy on both sides.) U+0000 deserves its own mention in the other direction: it is legal in the browser and rejected by common server text and JSON column types, so without this rule it becomes a 500.

The list above binds the client, before sending, and every JSON-backed store, before writing. In particular, callers may use PgAssetStore directly without crossing the HTTP boundary, so its put and metadata-replacing replace branches MUST enforce the same lossless domain before any registry or byte write. The decision MUST be made by inspecting the value, never by trial-serializing it: a JSON.stringify pre-flight runs caller code — toJSON, getters — before validation has looked at anything, and a stateful accessor can show the probe one value and the serializer another. A native TypeError from serialization MUST NOT escape; it is replaced by a typed error, as a native SyntaxError is on the read path. That is not only about error typing: V8's circular-structure message enumerates property names from the object it failed on, which would put caller-supplied metadata into an error message in direct violation of the egress rule above. A validation error names the offending path and MUST NOT include the offending value; that error-egress rule binds direct store calls exactly as it binds HTTP calls.

A server receives the output of a JSON parse, so most of that list cannot reach it — non-finite numbers are a syntax error and the rest are unrepresentable in JSON text. Its obligation is correspondingly short, and is what the 400 row of the error table refers to: reject a meta part that is not a JSON object, and reject -0 and U+0000 inside any string. Those are the only members of the domain that survive parsing.

Nothing reads metadata back to a caller. It is persisted so that provenance recorded at generation time — what produced these bytes, from what prompt or narration, with what voice — survives alongside the asset for later manifest and export work. A deployment should know what it is holding: metadata accumulates caller-supplied text that no code path currently returns, and it is subject to whatever retention and privacy posture that text requires.

Principal derivation and authorization Copy Chapter

The principal is derived server-side from the authenticated session and never appears in a path, query parameter, or body. This is the same non-negotiable that governs the other layers: a client-submitted principal is not proof of identity, and trusting one turns every route here into a lateral-authorization vulnerability. Every route requires authentication; there is no anonymous surface. A deployment's authenticate hook returning a principal in a malformed shape is 500 INTERNAL_ERROR rather than 400, because that is the deployment's bug and not the caller's.

A principal carries a required, opaque identity key, and that key is what every registry entry is partitioned on. This differs from the document layer, whose principal is all-optional because documents are author assets with no per-row ownership model; assets are partitioned, so the field the partition is keyed on cannot be optional. A principal that does not carry one has no asset capability at all and receives 403 FORBIDDEN_ASSETS on every route — never a shared partition. The distinction matters because an absent key is not a value: entries stored against one would collide into a single partition that every such principal could read, replace, and delete, which is a lateral-authorization hole produced by the type rather than by a bug.

Two of the three channels a principal or a hash could arrive through are closed structurally rather than by inspection: the route table admits no segment that could carry either, and no route takes a query string.

The third channel, headers, is closed by deriving no identity from it, and this contract deliberately does not attempt to police header names. A server MUST NOT take a principal, an owner, or a content hash from any request header except through the deployment's authenticate hook; no other header carries identity here, and one the implementation never consults for identity smuggles nothing. The rule is about what the implementation trusts, not a filter on traffic.

This is narrower than "reads no other header", and deliberately so: the transport headers below are read and acted on — Content-Type for the multipart boundary, Content-Length as an untrusted hint, and Content-Encoding rejected outright because it would defeat the decoded-size limits. Reading a header to decide how to frame or refuse a request is not the same as trusting one to say who is asking.

Rejecting suspicious header names instead would be worse than useless, and it is worth recording why so it is not reintroduced. A name-shaped denylist cannot distinguish a header that asserts identity from one whose name merely contains an identity word: User-Agent is caught by any pattern broad enough to catch X-Remote-User, and a server enforcing such a pattern answers 400 to every browser, SDK, and command-line client. More decisively, X-Forwarded-User, X-Remote-User, On-Behalf-Of, and their kin are exactly what an authenticating reverse proxy — auth_request, an OAuth2 proxy, an identity-aware gateway — injects for authenticate to read. A contract that rejects them forbids the deployment shape it most needs to support, and one that exempts them has rebuilt the enumeration it replaced.

A deployment that authenticates from front-door headers owns one obligation this contract states but cannot enforce: that front door MUST strip and reset those headers on every inbound request, so a client cannot supply its own. That is a property of the proxy, not of this handler.

Bodyless methods (GET, HEAD, DELETE) MUST reject any request body outright: a server that routes them without reading the body would let a prohibited field arrive unexamined. In the meta part of a write, a principal or contentHash member is rejected.

authorizeAssets is evaluated on the principal, the method, and the route before the entry is read, and MUST NOT receive the entry — otherwise a policy decision becomes entry-dependent and defeats the ordering rule below. It defaults to allowing any authenticated principal, matching document authorization rather than the deny-by-default of the administrative hooks. That default is not an absence of protection: the enforcing boundary is the principal recorded on every registry entry, checked on every route including every byte read. The hook is an additional policy layer for deployments that want one; the administrative hooks default to denial because they are privilege-escalation surfaces with no such per-row boundary behind them. A denial is 403 uniformly, on DELETE as on every other route — answering 204 to a caller whose policy forbids deletion would have them clear their reference and orphan the entry permanently.

Indistinguishability Copy Section

An id belonging to another principal and an id that was never allocated MUST produce byte-identical responses — same status, same code, same message, same details, and the same headers — on every route in the table. Headers are named explicitly because this contract puts an outcome-varying value in one: a later diagnostic or Retry-After could break indistinguishability exactly as an added details member would. DELETE answers 204 for both, and for an already-deleted id. Ownership MUST be checked before any classification that could vary the response, including anything derived from the entry's revision or media type; otherwise the classification itself becomes the oracle. ASSET_NOT_FOUND responses carry a fixed message and no details, so that a diagnostic added later cannot break this.

An asset id is an identifier, not a capability. Authorizing once and treating the id as a bearer token afterwards is forbidden: every byte read re-checks ownership. A URL valid for one principal must not serve bytes to another that obtained it.

Errors Copy Chapter

Every non-2xx response has this machine-readable JSON shape:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "@openmaic/storage: asset write body must carry a \"bytes\" part",
    "details": []
  }
}

details is optional. One class of response cannot carry this envelope: a 431, and anything else the framework emits before the handler runs, has neither a body of this shape nor an X-Error-Code. That is why the 431 row below names no code, and it is the reason the client rule is phrased as it is — a response the client cannot classify is never a miss.

Because HEAD responses have no body, every error response — on HEAD and, so that the two stay identical, on GET as well — MUST also carry the code in an X-Error-Code response header. Without it a client cannot tell ASSET_NOT_FOUND from ROUTE_NOT_FOUND from a gateway's own 404 on precisely the route it uses to decide whether a cached snapshot is still real. A HEAD response a client cannot classify is never a miss: it falls back to GET.

The client raises HttpAssetStoreError in every throwing case below.

Only ASSET_NOT_FOUND becomes a miss, and the client MUST match the code together with the status. Status alone is not sufficient: ROUTE_NOT_FOUND shares its status and means a broken deployment, and a 401 or 403 MUST NEVER be reported as a miss. A gateway answering 401 while echoing an error code must not be read as "the asset was deleted" — that reading turns an auth outage into apparent data loss, and a caller that reacts by clearing references turns it into real data loss.

A response the client cannot interpret — a non-JSON body under a 2xx status, an allocation response without an id member — raises MALFORMED_RESPONSE, a client-side code with no server counterpart, carried by the same error type. The client never lets a native SyntaxError, TypeError, or URIError escape in its place.

The content hash MUST NOT appear in any message or details, on any path, including internal failures. 5xx responses collapse to INTERNAL_ERROR with a fixed message for that reason as well as the usual one.

Retry and atomicity guarantees Copy Chapter

GET and HEAD are reads. DELETE is idempotent: removing an absent, already-removed, or foreign id succeeds. PUT /assets/{id}/content is idempotent in its effect on the bytes for the same body, though each application advances the revision — so a retry after an ambiguous failure leaves the bytes correct and the revision advanced twice, which is why the revision is opaque and compared only for equality.

POST /assets is not idempotent and is not implicitly retry-safe. Every call allocates, so a retried request that in fact succeeded leaves a second entry holding the same bytes. This is a direct consequence of server-assigned ids, and it is the property POST carries in the RuntimeStore HTTP contract. A caller that retries blindly should expect an orphan; a caller that cannot tolerate one must track the allocation it received.

A failed write leaves no registry entry, and no entry ever survives pointing at bytes that were not stored. It may leave bytes that nothing references — the crash window described under the byte layer, which costs storage rather than correctness. Whether it does depends on the layer: one inside the transactional store rolls back with the transaction and leaves nothing, while an object store cannot join that transaction and strands an object for reconciliation to take. There is no compare-and-swap. Concurrent replace calls on one id are last-writer-wins, and the revision reflects the order the server applied them. A resolve racing a replace observes either the pre- or the post-replace committed entry and never a mixture of the two.

Packages @Openmaic Storage Docs Document Http Contract (`packages/@openmaic/storage/docs/document-http-contract.md`) Copy Section

DocumentStore HTTP contract

This contract exposes the complete DocumentStore interface over JSON HTTP. All paths are relative to a deployment-defined base URL. Path segments are percent-encoded UTF-8 strings and MUST NOT be exactly . or .., because URL parsers normalize dot segments before routing. Request and response bodies use application/json; successful writes return 204 No Content.

Endpoints Copy Chapter

GET /documents returns only id, name, optional description, optional interactiveMode, optional taskEngineMode, createdAt, updatedAt, and sceneCount. Those fields are independent of the DSL version. Implementations MUST NOT migrate document content to produce this list and MUST tolerate an unknown or malformed stored version stamp.

Validation, versions, and JSON Copy Chapter

Servers run their configured validateStage and validateScene gates before writes. A full save validates the migrated aggregate and rejects duplicate scene ids, mismatched scene partitions, and non-finite order values before changing storage. putStage and putScene repeat the same boundary validation and require an existing document whose stored dslVersion is exactly the server's current DSL_VERSION. A stale document must first be loaded and saved as a full aggregate; a future document must never be downgraded. deleteScene has the same current-version guard, while whole-document deletion deliberately does not.

HTTP implementations carry data through JSON and therefore accept only plain values that serialize without changing meaning. They fail before sending or storing values such as Map, Set, Date, non-finite numbers, negative zero, undefined, bigint, sparse arrays, class instances, symbol/non-enumerable properties, U+0000 strings, and circular references. The opaque outline is not DSL-validated or migrated, but it is still subject to this JSON transport rule. A store exposed by the server MUST contain JSON-safe document, scene, outline, and summary values; the handler validates read payloads before serialization and returns 500 NOT_JSON_SAFE with the offending path if this invariant is violated.

The handler streams request bodies into a bounded buffer. maxBodyBytes configures the bound on createDocumentHttpHandler and composed/reference server factories; it defaults to 32 MiB. A body that crosses the bound is rejected immediately with 413 PAYLOAD_TOO_LARGE.

Reads are migrated on both sides of the wire. The backing store performs its normal migrate-on-read, and the HTTP client migrates the returned document again so an older server cannot leak a stale envelope into a newer application. The opaque outline is removed before DSL migration and reattached unchanged.

Authentication and authorization Copy Chapter

Documents are author assets, not learner-partitioned data. The contract does not prescribe a tenant or ownership model; deployments enforce their policy through the injected authenticate and authorizeDocuments hooks. The reference handler requires an authenticated principal for every document route. Its default authorization permits any authenticated principal; production deployments can supply authorizeDocuments to apply author, tenant, role, or document-level policy. Nothing on the wire names an owner, and the PostgreSQL backend keeps no ownership column on document_stages: a deployment that scopes documents per owner injects a PgDocumentStore bound to the request's owner with its own ownership relation (documentOwnership), so listings and writes are scoped by that relation while reads by id stay capability-by-id.

Errors Copy Chapter

Every non-2xx response has a machine-readable JSON body:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "@openmaic/storage: invalid stage ...",
    "details": []
  }
}

details is optional. Messages retain backing-store semantics so the client exposes the same useful wording as BrowserDocumentStore.

Only the machine-readable not-found codes are translated to null. Status alone is not sufficient. Authentication failures use 401 UNAUTHENTICATED, and authorization failures use 403 FORBIDDEN_DOCUMENTS.

Retry and atomicity guarantees Copy Chapter

Full saves are atomic: validation or any failed child write leaves the previous aggregate untouched. DELETE /documents/{stageId} and scene deletion are safely retryable. Stage and scene puts are idempotent for the same body, subject to the current-version guard. The contract does not add conditional requests or idempotency keys; deployments that retry an ambiguous full save must rely on the caller-owned stageId and replacement semantics.

Asset references, where a deployment maintains them Copy Chapter

A server whose asset backend tracks document references maintains them as a side effect of these write routes, inside the same transactions: a save replaces the stage's reference rows, a stage or scene put replaces that scope's, and a delete removes them and marks the entries that lost their last reference. A host that retires documents by tombstone rather than by deletion — keeping the rows so the retired id stays retired — releases their assets through an in-process store method (withdrawAssetReferences) instead, because that retirement is the host's own concept and this contract has no route for it. Nothing about this contract changes — not a request shape, not a response shape, not a status code, not an error — and a document write is never refused, delayed, or altered by what it references. An id the asset registry does not hold simply records no reference, exactly as an unknown id is a miss on the asset routes. A store constructed with assetReferencePrincipals goes one step further: an id naming an entry held by a principal that function does not return for the store's owner records no reference and commits nothing either, so one owner's document cannot commit, expose or pin another owner's allocation. The mechanism, and the reclamation it enables, is specified in the AssetStore HTTP contract.

Packages @Openmaic Storage Docs Kv Http Contract (`packages/@openmaic/storage/docs/kv-http-contract.md`) Copy Section

KVStore HTTP contract

This contract exposes the KVStore operations — get / set / remove / keys(prefix?) — over JSON HTTP for the account scope only. All paths below are relative to a deployment-defined base URL. Path segments and query parameter values are percent-encoded UTF-8 strings. Request and response bodies use application/json; successful operations with no return value respond with 204 No Content.

The conformance server in this package is test-only. It implements no authentication or authorization model beyond what the contract's response codes require; deriving the principal from an authenticated session is the reference server's job.

The scope is not on the wire Copy Chapter

KVStore distinguishes two scopes. account is user data a server-backed deployment syncs across devices (provider and model configuration, profile); device is machine-local state (theme, locale, layout) that must never leave the machine. That is a property of the primitive, not a deployment setting.

This contract therefore has no scope at all: no scope path segment, no scope query parameter, no scope header, no scope body field. There is nothing to set to device, so there is no configuration or client bug that could ship a device value to a server — a request carrying a device value is not a request this contract can express. Servers MUST reject a request that invents a scope in any of those channels with 400 VALIDATION_FAILED rather than ignoring it, so a client attempting to describe a scope fails loud instead of silently having its intent discarded. "Any channel" is exhaustive, and each of the four is a place a real client or proxy might reach for a scope:

• Path segment. The contract's segment after kv is entries or keys; a scope name there (/kv/device/keys, /kv/account/entries/{key}) is an attempt to route by scope and MUST be 400, not a 404 route miss. (A key named device is unaffected — that sits after entries, at /kv/entries/device.)
• Query parameter. A ?scope=… MUST be rejected.
• Header. There is no single canonical spelling, so the server MUST reject the whole prohibited set — at least scope, x-scope, kv-scope, and x-kv-scope. Checking only x-scope leaves the others open.
• Body. get, remove, and keys are bodyless: a server that routes them without reading the body would let GET /kv/keys with {"scope":"device"} succeed, the guarantee failing silently. So a bodyless method (GET, DELETE) MUST reject any request body outright, and only set reads a body, where a scope field is rejected.

Every one of {get, set, remove, keys} × {path, query, header spellings, body} is closed, and the shared suite pins each cell.

The client half mirrors this in three layers, only the last of which actually carries the weight:

1. HttpAccountKV is the only object in @openmaic/storage that can reach this contract, and its scope parameter admits 'account' alone — a literal 'device' at a call site is a type error. It also refuses one at runtime, because the type is not enough: TypeScript compares method parameters bivariantly, so this transport stands in for the wider KVStore wherever one is expected, and a caller holding it that way can pass any scope. Silently dropping that argument is how a device value reaches a server, so the transport takes the scope and fails loud on anything but account.
2. HttpKVStore — the full KVStore — is the one place the two scopes are told apart. An unrecognized scope is refused rather than folded into the account path: guessing would send a value the caller believed was device-local to a server.
3. HttpKVStore requires a LocalKVStore for the device scope — a store branded as keeping its values on this machine. KVStore alone is not enough, because a networked store satisfies it structurally: HttpAccountKV is a KVStore with one optional parameter fewer, so a KVStore-typed parameter would accept the very transport this design exists to exclude. The brand makes that a type error, and a runtime check refuses a remote store that a cast smuggled past the types.

There is no default and no fallback, so a deployment cannot end up with device values that have nowhere local to go.

The same pairing rule reaches the zustand adapter, which is where a store and a scope are chosen as separate arguments and therefore the easiest place to pair them wrongly: kvPersistStorage(store, 'device') requires a DeviceSafeKVStore at the type level and checks the brand at runtime. DeviceSafeKVStore is the capability that actually matters — "a device write stays on this machine" — and it is broader than LocalKVStore: it admits both a fully-local backend and the HttpKVStore composite, which routes device to its injected local backend while sending only account to a server. What it excludes is the pure HttpAccountKV transport, which has no local device backend and would put a device value on the wire; that store declares the capability false and is double-rejected.

Account settings are only as isolated as the deployment makes them Copy Section

The account scope is where a server-backed deployment syncs a user's settings across devices, and the contract's principal derivation keeps one account from addressing another's keys over the wire. That is a routing guarantee, not a storage one. Before enabling settings sync, a deployment MUST provide real per-user isolation of the stored rows (the (principal, key) partition enforced end to end, not merely by a query filter a bug could drop) and encryption at rest for the values, which hold user configuration and profile data. The reference server is a reference: it demonstrates the principal derivation, not a production isolation or encryption posture, and MUST NOT be exposed with real user data as-is.

A key is a truly opaque, unconstrained string Copy Chapter

A KV key is any string — of any length, containing any character, including NUL, separators, and things that look like structure. The KVStore primitive imposes no key-domain rules whatsoever: callers compose keys from unconstrained DSL identifiers (the DSL constrains ids only to be strings), and the browser primitive is a Map / Storage, which stores any string key. A rule in the key domain — a length cap, a / ban, a NUL ban — would be a transport concern reaching back into the primitive, and would make a key the browser can perfectly well store unreadable. There is no such rule, and no key validation. A server likewise MUST NOT reject a key for its content; it stores the decoded key as an opaque value — a bound parameter or a derived, constrained storage id — never as a path component or an unescaped fragment of a query, so a key like a/../../b (arriving percent-encoded as a%2F..%2F..%2Fb) is one opaque entry that traverses nothing.

Validity is a property of the key; reachability is a property of the transport. The two are kept separate, and this is the parity guarantee: a key is valid on every backend identically (all accept it), even where it is not reachable over a particular transport.

• The browser backend uses no transport and imposes nothing — every key round-trips.
• The HTTP backend carries a key as a URL path segment, so it inherits exactly three limits of that transport. Each is an HTTP-deployment concern, not a key-domain constraint, each makes the affected key fail loud rather than silently misbehave, and the browser backend stores every one of them fine:
  1. An unpaired UTF-16 surrogate has no percent-encoding — encodeURIComponent throws — so the client refuses it with KEY_NOT_ENCODABLE before building a request.
  2. A whole-key . or .. is normalized away by URL path parsing before the request is sent (/kv/entries/. collapses to the empty-key segment, /kv/entries/.. walks up a level), so sending it would silently alias a different entry. The client refuses these two whole keys with KEY_NOT_ENCODABLE as well. This is only the whole key: a key that merely contains a dot (a.b, prefix:id) is an ordinary segment and round-trips, and a ./.. prefix in a keys() query is unaffected (it is a query value, not a path segment).
  3. An extremely long key may exceed a deployment's request-target / header size ceiling (Node's default is ~16 KiB, above which the server answers 431 before routing). No length is invalid; a long key is simply not reachable past that transport bound.

None of these arise for the keys real callers produce (prefix:id from a DSL string). All are the URL transport's, not the key's; a deployment that must accept literally any key over HTTP would carry the key outside the URL path. This contract takes the simpler route and fails loud on the three cases above, and the browser backend is unaffected by all of them.

Endpoints Copy Chapter

Both read routes MUST be served with Cache-Control: no-store, and MUST NOT be cached by any intermediary. account is by definition the scope another device may have just written, and neither the client nor the server has a way to invalidate a cached copy when that happens — a cached read serves precisely the stale state this scope exists to move past. The client sends its reads with cache: 'no-store' for the same reason. Writes carry no such requirement, having nothing to read from a cache.

The value travels in an envelope rather than as the body itself. KVStore.get cannot distinguish a stored null from an absent key — both are null to a caller — but the wire still has to be unambiguous: a bare null body would be indistinguishable from an empty body or a stored null, leaving the framing to depend on Content-Length. The envelope makes "there is a value, and it is null" a statement the response can make. get maps 404 KEY_NOT_FOUND back to null, matching KVStore.get; the client MUST use the machine-readable code, not the status alone, so a 404 ROUTE_NOT_FOUND stays an error instead of masquerading as a missing key.

GET /kv/keys returns every matching key. The listing is not paginated, matching GET /documents in the DocumentStore HTTP contract; the primitive is sized for small configuration values, and a deployment that outgrows an unbounded listing needs a change to KVStore itself, not a second listing shape here.

The prefix is a literal, byte-for-byte comparison, not a pattern. A prefix is as opaque as a key: it too travels in the query string rather than as a path segment, so it may be empty (that is what "list everything" means), may be . or .. (legitimate prefixes of keys such as .hidden), and may contain any character a key may — %, _, \, /, and the rest. Only the transport-fatal characters and the DoS ceiling constrain it.

Because both the prefix and the keys it matches are opaque, a server MUST escape every metacharacter of its own query language before applying the comparison. In the obvious SQL translation, key LIKE prefix || '%', that means % and _, and the backslash — PostgreSQL's default LIKE escape character. Backslash is the one an implementer is most likely to skip, precisely because it is easy to assume a key could never contain one; it can — a key is opaque — and so can a prefix, and both reach the query. Escape all three, or the literal comparison silently becomes a pattern match. The result order is unspecified, but the listing MUST NOT repeat a key.

Value domain Copy Chapter

Values travel through JSON, so this backend accepts only plain JSON values that survive serialization without changing meaning. It MUST fail loud before sending values such as Map, Set, Date, non-finite numbers, negative zero, nested undefined, bigint, sparse arrays, symbol-keyed properties, non-enumerable properties, strings containing U+0000, class instances, and circular references. U+2028 and U+2029 are valid JSON string contents and MUST be accepted. Keys are held to the same rule, because a key becomes a URL path segment.

This is intentionally narrower than BrowserKVStore, whose JSON.stringify would quietly rewrite a Date into a string or drop a nested undefined. Where the browser backend is silently lossy, the HTTP backend refuses.

Both backends agree on one deliberate exception: set(key, value) where value has no JSON representation at all (undefined, a function, a symbol) is a removal, not a write. Storing such a value would produce an entry that throws on read, so the key is deleted instead.

Every backend decides that by inspecting the value, never by trial-serializing it, and this is a rule about all of them rather than an HTTP detail. A JSON.stringify pre-flight runs caller code — toJSON, getters — before any validation has looked at anything, which reclassifies values as deletes ({ toJSON: () => undefined } stringifies to undefined) and lets a stateful accessor show the probe one value and the serializer another. Two backends probing and validating in different orders would disagree about whether a write was a delete, which is precisely the divergence the shared suite exists to prevent. Scope and key are validated first, then the delete case is recognized by type, and only then is anything serialized. A value that still fails to serialize is refused rather than quietly deleted.

Principal derivation Copy Chapter

The principal is derived server-side from the authenticated session and never appears in a path, query parameter, or body. This is the same non-negotiable that governs learnerKey in the RuntimeStore HTTP contract: a client-submitted principal is not proof of identity, and trusting one turns every route here into a lateral-authorization vulnerability that lets one account read or overwrite another's configuration.

Every route requires an authenticated principal; there is no anonymous KV. Because keys are caller-chosen and this store holds user configuration, a deployment MUST scope every operation — including GET /kv/keys — to the derived principal, and MUST NOT expose a cross-principal listing on this contract.

Errors Copy Chapter

Every non-2xx response has this machine-readable JSON shape:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "@openmaic/storage: kv write body must carry \"value\"",
    "details": []
  }
}

details is optional.

Only KEY_NOT_FOUND becomes null. Status alone is not sufficient — ROUTE_NOT_FOUND shares its status and means a broken deployment, and a 401 or 403 must never be reported as a missing key.

A response the client cannot interpret — a body that is not JSON despite a 2xx status, a get body without a value member, a keys body that is not an array of strings — raises MALFORMED_RESPONSE, a client-side code with no server counterpart. It is a typed storage error like any other: the client never lets a native SyntaxError escape in its place.

Retry and atomicity guarantees Copy Chapter

Every operation is safely retryable. PUT is a whole-value replacement and therefore idempotent for the same body; DELETE is idempotent because deleting an absent key succeeds; both GET routes are reads. The contract offers no compare-and-swap: a concurrent write is last-writer-wins per key, which suits the small independent configuration values this primitive exists for. Callers needing an atomic read-modify-write should not model that state as KV.

Packages @Openmaic Storage Docs Reference Server (`packages/@openmaic/storage/docs/reference-server.md`) Copy Section

RuntimeStore, DocumentStore, and AssetStore reference server

The @openmaic/storage/server subpath exports a Node-only HTTP request handler implementing the RuntimeStore HTTP contract, plus the DocumentStore HTTP contract and AssetStore HTTP contract when their stores are supplied. It accepts injected store implementations; the runnable @openmaic/storage/server/reference composition creates and initializes PgRuntimeStore, accepts optional host-created document and asset stores, and demonstrates the required node-postgres checkout/transaction/release pattern.

The OpenMAIC application also mounts these same composed handlers as an
app-integrated Next.js route at /api/persistence. That embedded route is the
deployment form used by the repository's default Docker Compose deployment;
it changes the Fetch/Node request boundary only, not either HTTP contract.

This module is a reference, not a production authentication service. The example bearer authentication is fully impersonatable. A production host must supply its own authenticated identity and authorization policy. It must also terminate TLS, bound request sizes and timeouts, rate-limit abusive clients, keep database credentials outside the process image, and expose the service only through an appropriate application gateway.

Deployment Copy Chapter

Build the package and run the compiled entrypoint in a host that provides pg:

DATABASE_URL=postgres://user:password@host/database PORT=3000 \
  node packages/@openmaic/storage/dist/server/reference.js

The executable main() binds to 127.0.0.1; createReferenceRuntimeServer() only creates and returns an unbound Node Server. The default bearer token payload is used directly as the demo learnerKey, self-merge is the only allowed merge, and admin operations are denied. Supplying documentStore adds the DocumentStore routes to that same server; any authenticated principal is allowed by default, or authorizeDocuments can enforce deployment policy. The factory also accepts authenticate, authorizeMerge, authorizeAdmin, and validator overrides. Replace the policy hooks before exposing a deployment:

• authenticate(req) must validate a real credential and derive canonical learner and asset partition keys from server-controlled identity state.
• authorizeDocuments(principal, req) must establish that the principal may access the requested author document operation. The default permits every authenticated principal.
• authorizeAssets(principal, req) must establish that the principal may access the requested asset operation. The default permits every authenticated principal carrying an asset key; registry ownership remains mandatory on every operation.
• authorizeMerge(principal, fromKey, toKey) must explicitly establish that the principal may migrate the complete source partition into the destination identity. Default denial is intentional.
• authorizeAdmin(principal) must require a separately protected administrative role. Default denial is intentional.

The handler's payloadValidators option has the same whole-table replacement semantics as the BrowserRuntimeStore and PgRuntimeStore constructor option, and defaults to the DSL chat / quizAttempt skeleton table. Whatever you pass to the store, pass the same thing to the handler. createReferenceRuntimeServer() applies its payloadValidators override to both automatically. Its maxBodyBytes option applies to runtime and document routes and defaults to 32 MiB; oversized bodies receive 413 PAYLOAD_TOO_LARGE.

The package has no PostgreSQL driver runtime dependency. A host injects its Pool (or another compatible Queryable) and owns driver lifecycle. Every transactional operation must check out a fresh connection, issue BEGIN, run all callback queries on that same connection, issue COMMIT or ROLLBACK, and release it in finally.

Document endpoints Copy Chapter

Every document route requires an authenticated principal. By default,
authorizeDocuments allows any authenticated principal; production deployments
must replace that policy when documents are tenant-, role-, or author-scoped.

The reference composition applies its validateScene and validateStage
overrides to the HTTP handler; the host must configure the injected document
store with the same validators. Keep those validators in sync when composing
the lower-level handler yourself. Full response, validation, version, and retry
semantics are specified in the
DocumentStore HTTP contract.

Asset endpoints Copy Chapter

Every asset route requires an authenticated principal with an asset partition key. Supplying assetStore adds these routes to the composed server; authorizeAssets can apply an additional deployment policy before any registry entry is read. Supplying byteEgress forwards the option unchanged to the composed asset handler: { mode: 'redirect', collectionGraceMs } opts into indirect byte egress for GET /assets/{id}/content, and omitting it keeps direct egress. The full tradeoff is specified under Indirect byte egress in the asset HTTP contract.

Writes use bounded multipart/form-data; reads are private and uncached. The full media-type allowlist, size limits, response headers, and client snapshot rules are specified in the AssetStore HTTP contract.

Asset reclamation a host must schedule Copy Chapter

Nothing in this package runs on a timer. AssetCollector is a re-runnable pass a host has to schedule; left unscheduled, unreferenced entries and bytes grow without bound. A host composing this server owns that schedule — a periodic call to collect() in-process, a cron job against the same database, whatever fits the deployment. collect() is bounded per call and answers how many blobs it deleted; collectPass() answers that plus whether the batch was full, which is exactly "run again", and the entry counts below.

Three options decide how much of the two-level reclamation a deployment gets. All three are off or generous by default, so an existing deployment behaves as it did:

• PgDocumentStore's trackAssetReferences (default false) makes the document store maintain the document_asset_refs table and the entry lifecycle columns inside the write transactions it already opens. It is off by default because those are the asset backend's tables: a deployment that provisions documents without ensureAssetSchema() has none of them. Enable it by constructing the store you inject as documentStore with the option set; nothing about the document routes changes either way. A host that retires a document by tombstone — keeping its rows, so deleting it is never an option — must call store.withdrawAssetReferences(stageId) in-process when it retires one, or that document's assets stay referenced forever; it is the release half of deleteDocument on its own, it leaves the document rows alone so re-saving re-references normally, and it throws rather than answering if the store does not track references. There is no ordering to observe against the one-time backfill: that walk reads stored JSON, which a retirement deliberately does not change, so the call records the retirement itself and the walk skips that document — a retirement made mid-upgrade is honoured like any other. That record is the only thing that makes the walk skip a live-looking document, deliberately: while the walk is behind, an entry's own state cannot say whether some document it has not reached still names it, so the walk re-references whatever it finds and lets the entry pass, which skips referenced entries, sort it out.

• PgAssetStore's pendingTtlMs (default one day) is how long an allocated entry stays pending before it expires. The window it has to cover is "the bytes were stored, and then the document naming them was saved", which nothing on the wire leases, so a generous default is deliberate: unreclaimed bytes cost storage, while an expiry that fires before the document write costs a document its media. It is written on every allocation and only ever acted on by the entry pass below.

• PgDocumentStore's assetReferencePrincipals (default unset) scopes that maintenance to the entries of the principals it returns: a write references and commits only those, and an id naming any other principal's entry records nothing, like an unknown id. It is a function of the store's bound owner, evaluated per write, so a store re-bound with forOwner scopes to the new owner. A host that partitions its asset registry per owner returns that owner's principal (plus any partition every owner may use), and gives AssetCollector the same function so the one-time backfill applies the same scoping per document owner — together with the same documentOwnership relation, which is where the collector reads each document's owner (document_stages records none). The collector refuses the function without that option; pass false when documents have no owners. Without it, any document naming an id commits and pins that entry, whoever holds it.

• AssetCollector's documentReferences (default false) adds the entry pass, run ahead of the byte pass under the same batch cap and the same lock-and-re-check discipline. With it, the collector also backfills the reference table for a deployment upgrading into this level, in bounded chunks (referenceBackfillBatchSize, default fifty documents), and releases nothing until that walk has covered every document. Every transaction it opens carries a lock-wait budget, as the registry's writes do, so one stuck holder cannot park a scheduled pass indefinitely. A failure at this level — a lock timeout, a document the walk cannot read — is reported after the byte pass rather than instead of it, so a contended entry level never costs a deployment its byte reclamation for that interval.

Schedule the upgrade window when the deployment is quiet. The pass that finishes the backfill walk also runs the one-time legacy mark, which touches every entry written before the lifecycle columns existed: it locks them in batches of batchSize, marks each batch committed, and stamps the ones no document turned out to name. Each batch is one short transaction and the work is monotonic — what a batch marked stays marked, and a batch that fails is simply redone on a later pass — so nothing is lost either way. But those rows are the same rows a document save locks, so while the mark runs, a save touching one of them waits, and a save that waits past the collector's lock-wait budget fails with a retryable StorageLockUnavailableError. On a busy deployment run the first passes out of hours; a client that retries such a failure sees nothing else.

Waiting is all it does: every writer of asset_entries in this package — a document save, the collector's backfill, the collector's mark — takes all of one transaction's entry row locks in a single ascending statement before it writes anything, so two of them queue rather than deadlock. That property depends on the rule, not on luck: a writer added later that locks several entry rows in more than one statement, or in another order, puts the deadlock back.

Every pass also sweeps one bounded batch of live entries. Once the backfill walk is done, each pass locks the next batchSize committed, unstamped entries — an ascending batch, paged by a cursor that wraps at the end of the table — and stamps any of them no document references. It exists for the rows no write will ever stamp: a reference row that went away without the document write that would have stamped its entry — rows removed out of band, or a restore that reinstated documents but not the reference table. Such an entry is committed, unstamped and referenced by nothing, and without the sweep nothing would look at it again — it, its bytes and its share of the principal's quota would be held forever. The sweep is not a repair for mixed tracking states. A deleteDocument issued by a store with trackAssetReferences off deletes the document rows and nothing else, and no foreign key ties document_asset_refs to them, so that document's reference rows survive it: the entry stays referenced, by rows naming a stage that no longer exists, and neither the sweep nor anything else in this package reclaims those rows. That is one more reason to roll the two halves back together, below. The cost is one short transaction per pass holding one bounded batch of live rows, so a concurrent save touching one of those rows queues behind it; an entry that becomes an orphan is reached within ceil(entries / batchSize) passes.

documentReferences requires trackAssetReferences, and the collector enforces it. They are two halves of one mechanism: the document store is what commits an entry and what records the references the pass reads. A collector running the entry pass against a document store that maintains nothing would see every entry as pending and release each one when its TTL expires, while the documents naming them are still there.

That is not left to the operator to get right. A document store with trackAssetReferences records a marker row in the registry's own schema on every write that maintains references, and the collector reads it before its entry pass: absent, the entry level refuses with AssetReferenceTrackingNotEnabledError and nothing is released. Because that marker arrives with the first such write, a host that can vouch for every writer on the database should call store.declareAssetReferenceTracking() once at startup, after ensuring the schemas — otherwise a freshly installed or freshly switched-on deployment refuses on every interval until somebody happens to save a document, the backfill never starts, and the refusal looks like a broken pairing rather than an idle one. The blob pass still runs — it is correct with or without a reference writer — so a deployment that trips this keeps reclaiming bytes while it fixes the configuration. The check is a marker rather than "are there any reference rows", because an empty table is indistinguishable from documents that reference nothing.

The check catches enabling the halves in the wrong order; it does not catch rolling one back. The marker is never removed, so a deployment that has run with both and then sets trackAssetReferences back to false — a revert, a flag flip, a replica deployed from an older configuration — keeps passing the check while its new allocations are never committed and are released on their TTL. The same mixture has a quieter second symptom: a store with tracking off cannot touch the asset backend's tables at all, so a delete it issues leaves behind the withdrawal record of a retired document, and the collector's one-time walk will then skip whatever later claims that id. Roll the two back together, and prefer deriving both from one setting so they cannot drift. A heartbeat would close this, and is deliberately not used: it would make an idle deployment refuse to reclaim its own expired pending entries for the sole reason that nobody wrote a document that week.

One grace period (graceMs, default one hour) governs both levels: an entry and its bytes are two rows describing one asset, and separate windows would only let them disagree about how long an undo has. A deployment using indirect byte egress must keep its signed-URL lifetime far below that grace; assertSignedUrlTtlWithinGrace states the rule, and the asset handler applies it already.

Endpoint authorization matrix Copy Chapter

The matrix treats learner, merge, and admin credentials as separate capabilities. An admin-only or merge-only credential does not implicitly own a learner partition; a deployment may combine capabilities, but every applicable check still has to pass.

Threat model Copy Chapter

learnerKey is an opaque partition key, never a credential. An attacker can alter path segments and JSON bodies, so trusting a submitted key enables lateral movement: reading another learner's sessions or records, writing records into their sessions, changing status, or deleting their data. The handler authenticates every contract operation and compares stored or submitted learner ownership before touching learner-scoped data. Direct stage / learner partition mismatches return 403 FORBIDDEN_LEARNER; missing credentials return 401 UNAUTHENTICATED.

Session-scoped routes deliberately conceal whether another learner's session ID exists. A credential with a different learnerKey receives the same 404 SESSION_NOT_FOUND as an absent session, and ownership is checked before future-version classification so version metadata cannot disclose existence. A principal with no learnerKey is different: it lacks the learner capability entirely and receives 403 FORBIDDEN_LEARNER on every learner-scoped route.

An asset id is an identifier, not a bearer token. Every asset operation rechecks the authenticated principal's ownership, including every byte read. An id belonging to another principal and an id that was never allocated are indistinguishable on every route: reads and replacements return the same fixed 404 ASSET_NOT_FOUND, while deletion succeeds as the same no-op.

Merge is a privilege-escalation boundary because it rewrites every source session across every stage. Merely owning either key is insufficient in a real identity system: the authorization hook must verify the account-linking or identity-upgrade proof for both the source and destination. The default is deny.

Stage cascade deletion and whole-runtime deletion are admin-plane capabilities. If exposed to ordinary learners they can erase every partition on one stage or across the entire runtime store, so both routes are controlled by the separate admin authorization hook and denied by default. Production systems should isolate admin credentials, audit decisions, protect against confused-deputy use, and avoid deriving admin authority from a learner-controlled claim.

Authentication failures and authorization denials should be logged without recording bearer credentials or sensitive request payloads. Operators should monitor repeated cross-learner denials, merge attempts, and admin-plane calls as possible account-enumeration or privilege-escalation signals.

Concurrency semantics during merge-time deletion Copy Section

mergeLearner and deleteSession may race. If deletion verifies ownership and a merge changes ownership immediately afterward, the resulting deletion is equivalent to the legal serial order in which delete happens before merge. The handler therefore re-reads and re-checks ownership immediately adjacent to the delete call to shrink the race window; this is treated as a linearizable ordering case, not as an API or schema defect. A store-level conditional delete such as delete-if-owner could further harden this boundary in the future.

Version and concurrent-write classification Copy Section

Reads return future-stamped sessions and their records without applying a version gate, while every delete endpoint remains version-agnostic so it can clean up data written by a newer client. Only the three mutating operations that can rewrite session-owned data apply the future-version guard: status updates, record appends, and learner merges return 409 FUTURE_VERSION rather than mutating a future-stamped session.

Status updates and record appends authorize and validate the session before entering the backing store's write transaction. If the store then rejects the write because a concurrent operation deleted or completed the session, the handler re-fetches the session instead of classifying the failure from driver or error-message text. A now-absent session returns 404 SESSION_NOT_FOUND; a session whose current status is no longer active returns 400 VALIDATION_FAILED and reports that status. If the structured re-fetch still finds an active, current-version session, or if the re-fetch itself fails, the original failure remains an undisclosed 500 INTERNAL_ERROR.

Packages @Openmaic Storage Docs Runtime Http Contract (`packages/@openmaic/storage/docs/runtime-http-contract.md`) Copy Section

RuntimeStore HTTP contract

This contract exposes the complete RuntimeStore interface over JSON HTTP. All paths below are relative to a deployment-defined base URL. Path segments and query parameter values are percent-encoded UTF-8 strings. Identifiers used as path segments MUST NOT be exactly . or .., because URL parsers normalize those dot segments before routing. Request and response bodies use application/json; successful operations with no return value respond with 204 No Content.

Endpoints Copy Chapter

GET /runtime/sessions/{sessionId}/records returns an empty array when the session has no records, matching RuntimeStore.listRecords. For an absent session a server MAY answer 404 SESSION_NOT_FOUND instead of 200 [] — authorization-aware servers SHOULD, so absent and unowned sessions are indistinguishable — and the client MUST map that 404 back to an empty array, preserving the store contract. Deleting an absent target succeeds.

Server-assigned sequence Copy Chapter

seq is server-assigned. The append request body is a RuntimeRecordInit. If it includes seq, that value is ignored; the store's assigned value is authoritative. The server allocates the next per-session monotonic sequence number atomically with the insert, starting at 0, and the response returns the full RuntimeRecord, including the assigned seq.

Likewise, runtimeDslVersion is server-assigned when a session is created. If the request body includes runtimeDslVersion, that value is ignored; the store's assigned value is authoritative.

Compare guards and session transitions Copy Chapter

expectedLastSeq is an optional compare-and-swap guard shared by status updates and record appends. A non-negative integer means the caller observed that sequence at the record tail; null means the caller observed no records. Omission means no precondition. The server compares the value with the actual tail inside the same transaction as the write. A mismatch commits neither the status update nor the append and returns 409 RUNTIME_APPEND_CONFLICT with the expected and actual tails in error.details.

An append may also include a top-level sessionTransition object with { "status", "updatedAt" }. The server validates and commits the completed parent session in the same transaction as the record. A tail conflict or validation failure persists neither change. For example:

{
  "id": "record-1",
  "sessionId": "session-1",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "payload": null,
  "expectedLastSeq": null,
  "sessionTransition": {
    "status": "completed",
    "updatedAt": "2026-01-01T00:00:01.000Z"
  }
}

Payload domain Copy Chapter

HTTP implementations carry record payloads through JSON and therefore MUST accept only plain JSON values that survive serialization without changing meaning. They MUST fail loud before sending values such as Map, Set, Date, non-finite numbers, negative zero, nested undefined, bigint, sparse arrays, symbol-keyed properties, non-enumerable properties, arrays with non-index own properties, strings containing U+0000, class instances, and circular references. U+2028 and U+2029 are valid JSON string contents and MUST be accepted. This is intentionally narrower than BrowserRuntimeStore, whose structured-clone persistence can preserve values such as Map, Set, and Date that JSON cannot.

The reference handler streams request bodies into a bounded buffer. maxBodyBytes configures the bound on the runtime, composed-storage, and reference-server factories; it defaults to 32 MiB. A body that crosses the bound is rejected immediately with 413 PAYLOAD_TOO_LARGE.

learnerKey security model Copy Chapter

learnerKey appears in paths, query parameters, and request bodies, but the server MUST derive or verify learnerKey from the authenticated session and MUST NOT blindly trust the client-submitted value. learnerKey is an opaque partition key, not proof of identity or authorization; trusting it verbatim creates a lateral-authorization vulnerability that lets one learner read, merge, or delete another learner's runtime data. The same rule applies to both keys in mergeLearner; authorization policy must explicitly permit the authenticated principal to migrate the source partition into the destination partition.

The conformance server in this package is test-only and does not implement an authentication or authorization model; deriving learnerKey from authentication is left to the reference server in #939 Part D.

Errors Copy Chapter

Every non-2xx response has this machine-readable JSON shape:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "@openmaic/storage: invalid runtime session ...",
    "details": []
  }
}

details is optional. message preserves the semantic wording of the backing store error so an HTTP client can reconstitute the fail-loud exceptions callers receive from BrowserRuntimeStore.

The client MUST use the machine-readable code, not status alone, when an operation has special behavior. In particular, only SESSION_NOT_FOUND is translated to undefined by getSession. Sessions returned by reads MUST be forward-migrated through the client's migrateRuntime before they are returned, because the server may lag the client schema version. Corrupt sessions remain fail-loud on direct reads and are omitted from partition listings, matching BrowserRuntimeStore.

Retry and atomicity guarantees Copy Chapter

mergeLearner, DELETE /runtime/sessions/{sessionId}, DELETE /runtime/stages/{stageId}/learners/{learnerKey}, and DELETE /runtime/stages/{stageId} MUST be safely retryable. Repeating a completed merge moves 0; repeating a delete succeeds with 204. A merge is atomic across every matching source session and MUST NOT expose a partial move. Delete endpoints cascade atomically to the target sessions' records.

The test-only conformance server may report a future-stamped-row conflict encountered mid-merge as 500 INTERNAL_ERROR; structured classification of that specific case is deferred to the real Part D server implementation.

POST /runtime/sessions and record append are not implicitly retry-safe: clients must not retry them after an ambiguous transport failure unless a deployment adds a separate idempotency-key policy. Session ids and record ids remain caller-owned uniqueness keys, while record seq remains exclusively server-owned.

Packages Docs Content Docs Configuration.Ar (`packages/docs/content/docs/configuration.ar.mdx`) Copy Section

title: شرح الإعدادات Copy Chapter

لدى OpenMAIC ثلاثة مصادر للإعدادات، ولكل منها مهمة واحدة:

DATABASE_URL is required; other environment variables are optional (see Deployment). Providers that use server credentials for model selection also need authorized model lists, as described below. See .env.example for environment variables, openmaic.example.yml for a sample model configuration, and Supported models for preset and model IDs.

في الإصدارات السابقة كانت النماذج تُضبط فقط عبر متغيرات بيئة المزودين وserver-providers.yml وDEFAULT_MODEL وMODEL_ROUTES. ما زالت هذه الطرق تعمل حاليًا، باستثناء MODEL_ROUTES، لكنها مهملة؛ راجع الانتقال من الإعدادات القديمة.

النماذج والمزودون Copy Chapter

المفاهيم Copy Section

• المزود (provider): حساب يستطيع الخادم استدعاءه، مثل مفتاح OpenAI أو Token Plan من MiniMax أو خادم متوافق مع OpenAI تستضيفه بنفسك. لكل مزود معرّف تختاره أنت، وإعداد مسبق (preset) يحدد المورّد والقدرات التي يغطيها.
• الخانة (slot): موضع في المنتج يستخدم الذكاء الاصطناعي، مثل مخطط المقرر أو محتوى الشرائح أو تحويل النص إلى كلام أو البحث على الويب. تشكّل الخانات شجرة لكل قدرة، والخانة التي ليس لها تعيين تتبع الخانة الأم.
• التعيين (assignment): المزود والنموذج اللذان تستخدمهما الخانة (provider:model)، مع معاملات استدعاء ونموذج احتياطي اختياريًا، أو null لإيقاف الخانة.

تكون القدرة متاحة فقط عندما تُحل خانتها إلى تعيين. لا توجد مفاتيح تشغيل وإيقاف منفصلة.

openmaic.yml Copy Section

يقرأ الخادم openmaic.yml من المجلد الذي يبدأ فيه (جذر المستودع؛ /app في صورة Docker). لاستخدام مسار آخر اضبط OPENMAIC_CONFIG؛ يُحل المسار النسبي انطلاقًا من المجلد نفسه، ويجب عندها أن يكون الملف موجودًا. بدون الملف يستخدم الخادم إعدادات الويب، والمتغيرات القديمة ما دامت مضبوطة.

يُقرأ الملف مرة واحدة عند بدء التشغيل: أعد تشغيل الخادم بعد تعديله. يُتحقق من الملف كاملًا قبل بدء الخادم. أي ${VAR} غير مضبوط، أو إعداد مسبق أو خانة غير معروفين، أو إشارة إلى مزود غير مُعلن، أو مزود لا يقدم قدرة الخانة، يوقف الخادم، وتُعرض كل مشكلة مع موضعها:

[boot] Invalid server configuration; the server will not start: Invalid model configuration in /app/openmaic.yml:
  - providers.openai.apiKey: environment variable OPENAI_API_KEY is not set
  - slots.course.outlines: unknown slot

لا تكتب الأسرار في الملف نفسه: أشر إليها بـ ${VAR} واضبط المتغير في البيئة. القيم الآتية من المتغيرات لا تُطبع أبدًا في هذه الرسائل.

مثال كامل Copy Section

/* Detailed source-code truncated for AI context efficiency. */

مع هذا الملف تكون الخانات المكتوبة تحت slots قيمًا افتراضية للخادم: يمكن للمستخدمين تغيير كل منها في إعدادات النماذج، باستثناء tts الذي يثبّته lock للجميع. خانة المحادثة غير المذكورة، مثل course.agents، تتبع أصلها (llm)؛ وجذر القدرة غير المذكور، مثل asr أو document، يبقى غير مُهيأ حتى يعيّنه مستخدم. ومع allowUserKeys: false يختار المستخدمون فقط من بين المزودين المعلنين هنا.

المزودون Copy Section

كل إدخال تحت providers يعلن مزودًا واحدًا. المفتاح هو معرّفه الذي تستخدمه الخانات للإشارة إليه: من 1 إلى 63 حرفًا من الأحرف الصغيرة والأرقام والشرطات، يبدأ بحرف أو رقم.

تغطي معظم الإعدادات المسبقة قدرة واحدة وفق السجلات المدمجة: الإعداد openai للمحادثة فقط، أما صور OpenAI وتحويل النص إلى كلام والتفريغ الصوتي فهي الإعدادات openai-image وopenai-tts وopenai-whisper. أعلن مزودًا واحدًا لكل قدرة، وأشر إلى ${VAR} نفسه عندما يغطي مفتاح واحد عدة قدرات. إعدادات Token Plan المسبقة (minimax وtokendance وvolcengine-ark وkimi-coding-plan) تغطي عدة قدرات بمفتاح واحد، كل منها على عنوان الخطة الخاص. يستبدل baseUrl على المزود العنوان لكل القدرات التي يغطيها، لذا لا تضع baseUrl لـ Token Plan إلا إذا انتقلت كل قدراته معه.

يوقّع Amazon Bedrock (preset: bedrock) الطلبات بسلسلة بيانات اعتماد AWS على الخادم (البيئة أو profile أو role)، ويقرأ المنطقة من BEDROCK_REGION أو AWS_REGION أو AWS_DEFAULT_REGION؛ وapiKey رمز bearer اختياري.

الخانات Copy Section

كيف تُحل الخانة:

• يبدأ الحل من خانة الاستدعاء ويصعد نحو جذر القدرة، وأول تعيين يُعثر عليه هو الذي يُستخدم. لذلك يكون تعيين الخانة الأم هو الافتراضي لشجرتها الفرعية كلها، وتغيير الأم يغيّر كل خانة فرعية ليس لها تعيين خاص.
• داخل شجرة فرعية مقفلة (الخانة أو أحد أسلافها مذكور في lock، أو lock: all) لا يُعتد إلا بـ openmaic.yml: يصعد البحث حتى الخانة المقفلة، وأول تعيين يكتبه الملف هو الذي يُستخدم. وفي كل مكان آخر يغلب اختيار المستخدم: يُبحث أولًا عن تعيين مساحة العمل نفسها من الخانة صعودًا حتى الجذر، ولا يُبحث عن القيم الافتراضية التي يكتبها openmaic.yml إلا إذا لم يوجد أي تعيين، ومن الخانة صعودًا أيضًا. لذلك تتبع الخانة التي لم تغيّرها مساحة العمل اختيارَها على الخانة الأصل، حتى لو كُتبت عليها قيمة افتراضية للخادم؛ فقيم الخادم ليست إلا قيمًا افتراضية.
• null يوقف الصعود: الخانة وكل الخانات تحتها التي ليس لها تعيين خاص تكون موقوفة.
• إذا وصل الحل إلى الجذر دون تعيين، تبقى القدرة غير مُعدة. تفشل الاستدعاءات بخطأ يذكر اسم الخانة، ولا يوجد رجوع إلى أي مورّد.
• المتطلبات تخص الخانة التي تعلنها، وتُفحص على النموذج الذي تُحل إليه الخانة، سواء كان معيّنًا لها أو موروثًا. تتطلب agent استدعاء الأدوات؛ وإذا قال الكتالوج المدمج إن نموذجها لا يدعمه، يرفض الوكيل العمل بدل أن يتدبر أمره. النموذج غير الموجود في الكتالوج مسموح به. لا متطلبات لـ agent.title، لذا يمكن أن يستخدم نموذجًا أصغر.

التعيينات Copy Section

للتعيين أربعة أشكال:

slots:
  llm: openai:gpt-5.5            # مزود:نموذج
  webSearch: tavily              # المزود وحده: نموذجه الافتراضي
  course.outline:                # كائن مع معاملات
    model: openai:gpt-5.5
    fallback: anthropic:claude-sonnet-4-6
    thinking: { effort: low }
  video: null                    # موقوف

يقبل شكل الكائن الحقول التالية:

يجب ألا تضبط خانة agent القيمة thinking.effort: فالنقل الذي يستدعي الأدوات لا يستطيع الجمع بين شدة الاستدلال وأدوات الدوال.

الإشارة إلى المزود وحده Copy Section

الإشارة بدون :model تعني النموذج الافتراضي للمزود: النموذج الذي توصي به Token Plan لتلك القدرة، وإلا فالنموذج الافتراضي في السجل المدمج. معظم خدمات البحث والمستندات لا تتيح اختيار نموذج، لذا فالشكل المعتاد هو webSearch: tavily أو document: mineru-cloud. خانات المحادثة تسمّي نموذجًا دائمًا؛ وllm: openai يُرفض عند بدء التشغيل.

النماذج الاحتياطية Copy Section

تنطبق النماذج الاحتياطية على خانات النماذج اللغوية فقط: llm وكل الخانات تحته. يُرفض fallback في خانة tts أو asr أو image أو video أو webSearch أو webFetch أو document، عند بدء التشغيل في openmaic.yml وعند الحفظ في إعدادات النماذج.

يُجرَّب fallback الخاص بالخانة مرة واحدة عندما يفشل استدعاء النموذج الأساسي، بعد محاولاته الخاصة، بفشل قابل لإعادة المحاولة: خطأ عابر من SDK، أو انتهاء المهلة، أو خطأ شبكة، أو تجاوز حد المعدل (429)، أو نقص السعة (503)، أو مخرجات فارغة. أما إذا رفض المزود الطلب صراحةً لنفاد الحصة (برمز متوافق مع OpenAI مثل insufficient_quota، أيًّا كانت حالة HTTP)، فلا يُعاد الاستدعاء على النموذج الأساسي، بل ينتقل فورًا إلى النموذج الاحتياطي. رفض المحتوى لأسباب السلامة وأخطاء 4xx الأخرى لا تؤدي إلى الرجوع الاحتياطي. ينطبق الرجوع الاحتياطي على الاستدعاءات العادية والمتدفقة معًا، ويستخدم معاملات thinking الخاصة بالخانة.

النموذج الاحتياطي جزء من التعيين ويُورث معه: course.content.slide بلا تعيين خاص تستخدم نموذج course.content ونموذجه الاحتياطي. الخانة ذات المتطلبات لا تعيد المحاولة على نموذج احتياطي لا يلبيها.

إيقاف قدرة Copy Section

اكتب null في خانتها. video: null يوقف توليد الفيديو افتراضيًا، ويظل بإمكان المستخدمين تشغيله في إعدادات النماذج؛ أضف lock: [video] لإبقائه موقوفًا للجميع. وcourse.content.pbl: null يوقف توليد مشاهد PBL بينما يواصل باقي course.content العمل. يفشل استدعاء الخانة الموقوفة فورًا، وتجيب مسارات الوسائط بـ 403 بدل اختيار مورّد آخر.

القيم الافتراضية والأقفال وإعدادات النماذج Copy Section

ما يكتبه openmaic.yml تحت slots هو القيمة الافتراضية للخادم: يمكن للمستخدمين تغييرها في إعدادات النماذج، حيث تقول البطاقة افتراضي الخادم، ويلغي إعادة التعيين إلى افتراضي الخادم تغييرهم. وما يذكره تحت lock يثبّته المسؤول للجميع مع شجرته الفرعية كاملة:

lock: [llm, video]   # هذه الخانات وكل الخانات تحتها
# lock: all          # كل الخانات

• يجب أن تكون كل خانة يذكرها lock مكتوبة تحت slots (وnull يُحتسب: video: null مع lock: [video] يبقي الفيديو موقوفًا للجميع). الخانة المجهولة، أو الخانة المقفلة التي لا يكتبها slots، توقف الخادم عند بدء التشغيل مع ذكر موضعها (lock.1: ...).
• الخانة المقفلة تثبّت أبناءها أيضًا: مع lock: [llm] لا يستطيع أي مستخدم ضبط course.outline أو أي خانة أخرى لنموذج اللغة، وتُحل كلها من openmaic.yml وحده.
• lock: all يثبّت كل الخانات، مكتوبة أو لا؛ ويصبح جذر القدرة الذي لا يكتبه slots غير مُهيأ للجميع. لكن webFetch غير المحدد يستخدم builtin؛ ولتعطيله اضبط webFetch: null.
• تجتمع null والقيمة الافتراضية والقفل كما هو متوقع: video: null وحدها موقوفة حتى يشغّلها مستخدم؛ ومع lock: [video] تبقى موقوفة.

تأخذ الإعدادات أحد ثلاثة أشكال، بحسب الإعداد:

قاعدة واحدة تحكم كل عنصر تحكم: لا يُعرض إلا إذا كان استخدامه يمكن أن يغيّر شيئًا. لا يظهر تبويب في خدمات النماذج، ولا إضافة خدمة فيه، إلا ما دامت لقدرته خانة يستطيع المستخدم ضبطها؛ ولا يظهر Token Plan إلا ما دامت خطة ما قادرة على ملء خانة غير مقفلة، ولا يمس ربط الخطة أي خانة مقفلة. البطاقة المقفلة في إعدادات نماذج الدورة سطر واحد للقراءة فقط عليه ثبّته المسؤول. ولا يظهر منتقي النماذج في الصفحة الرئيسية إلا عندما يمكن تغيير النموذج الافتراضي (llm غير مقفلة ويقدّم مزود ما نموذج لغة).

تقرأ إعدادات النماذج في تطبيق الويب الشجرة نفسها وتعدّلها لمساحة العمل الحالية:

• Token Plan: يضيف ربط خطة مزودها بالمفتاح ويملأ الخانات التي توصي بها الخطة ولم تُعيّن بعد. يزيل فك الربط المزود، وتعود الخانات التي كانت تستخدمه إلى اتباع خاناتها الأم.
• خدمات النماذج: تبويب لكل قدرة (نماذج اللغة، الصور، الفيديو، تحويل النص إلى كلام، التعرف على الكلام، تحليل المستندات، البحث على الويب) يسرد خدماتها. يُعرض مزودو openmaic.yml للقراءة فقط ودون أي معلومات عن مفاتيحهم. الخدمة التي تعدّها مساحة العمل تصبح مزودًا لها: مفتاحها للكتابة فقط ولا يظهر إلا كقناع مثل …abcd، والعنوان المخصص متاح لنماذج اللغة فقط (تستخدم Azure Speech نقطة النهاية الرسمية لمنطقتها، مثل https://<region>.tts.speech.microsoft.com)، والخدمات المستضافة ذاتيًا وأزواج المفاتيح تُعدّ في openmaic.yml. تتحقق أزرار الاختبار من المزود المحفوظ على الخادم.
• إعدادات نماذج الدورة: النموذج الرئيسي هو خانة llm، ولكل مرحلة في المسار خانتها (اتباع النموذج الرئيسي يعني أنه لا تعيين خاصًا بالمرحلة)؛ وتضبط مفاتيح الصور والفيديو والكلام والبحث والتفريغ خانتها على null. الخانة المقفلة سطر واحد للقراءة فقط، والخانة التي على قيمة الخادم الافتراضية تعرض إعادة التعيين إلى افتراضي الخادم بعد أن يغيّرها المستخدم.

تُستورد إعدادات المزودين التي حفظها المتصفح في الإصدارات السابقة (المزودون بمفاتيحهم وعناوينهم الأساسية، والنموذج المختار، والاشتراك في Token Plan، واختيار كل قدرة) إلى مساحة العمل مرة واحدة. لا يستبدل الاستيراد أي إعداد موجود في مساحة العمل ولا أي خانة يقفلها openmaic.yml، ويتخطى العناصر التي يرفضها allowUserKeys: false أو التحقق. بعد استجابة 2xx، لا يُحذف من المتصفح إلا ما أصبحت مساحة العمل تحتفظ به: كل عنصر تخطاه الخادم (عنوان مخصص لخدمة وسائط، أو إعداد مسبق لا يحق لمساحة العمل استخدامه، أو معرّف مزود يعلنه النشر، ...) يبقى في هذا المتصفح مع مفتاحه، ولا يُرسل مرة أخرى، ويُعرض مع السبب في الإعدادات ← خدمات النماذج (مع تنبيه لمرة واحدة) حتى يُعاد إعداده أو يُتجاهل. يُستورد مزود Azure Speech مع نقطة النهاية الرسمية لمنطقته. بعد 400 يُرفض الاقتراح كله: لا يُرسل مرة أخرى، وتبقى عناصره مع مفاتيحها في هذا المتصفح وتُعرض مع العناصر التي تم تخطيها. ويُحذف الاقتراح غير المقروء؛ ولا يبقى في المتصفح لمحاولة لاحقة إلا عند 401 أو 404 أو 409 أو 5xx أو خطأ في الشبكة. يصبح الإدخال الصوتي الذي أُوقف صراحةً asr: null، وتصبح السرد أو الصور أو الفيديو التي أُوقفت مع وجود مزود صالح لها tts: null أو image: null أو video: null (وتبقى الخانة التي يقفلها openmaic.yml كما هي). يجب إعداد ما يلي يدويًا من جديد: نماذج المراحل (في إعدادات نماذج الدورة، أو slots في openmaic.yml)، وإعدادات الاستدلال (thinking على الخانة)، ومزودو الكلام والتفريغ المخصصون وزوج مفاتيح AliDocMind (في openmaic.yml؛ تبقى في المتصفح وتُعرض مع العناصر المتخطاة)، وخلفية VoxCPM (options.backend)، ومصادر بحث Baidu الفرعية (تُطبّق القيم الافتراضية للخادم). لا يُنقل إيقاف البحث (كان يوقف بحث الدورة فقط، بينما واصلت المحادثة والوكيل البحث)، ولا المفتاح المتوقف بحكم القيمة الافتراضية فقط: كل قدرة تعمل الآن متى حُلت خانتها.

مساحة العمل هي المالك (owner) بمعنى توثيق التخزين الدائم: في إعداد Docker Compose الافتراضي (وضع المستخدم الواحد) توجد مساحة عمل واحدة، وفي النشر متعدد المستخدمين يكون لكل حساب مسجّل مساحة عمله.

allowUserKeys Copy Section

allowUserKeys: false

يحدد allowUserKeys (الافتراضي true) ما إذا كان بإمكان المستخدمين إضافة مزودين ومفاتيح وخطط Token Plan خاصة بهم. مع false يختار المستخدمون فقط من بين المزودين الذين يعلنهم openmaic.yml، وللخانات غير المقفلة فقط: لا يُعرض Token Plan ولا إضافة الخدمات، ولا تُستخدم بعد ذلك المزودات التي أضافتها مساحات العمل من قبل. ويتم حينئذ تجاهل الطلبات التي لا تزال تسمّي نموذجها أو مفتاحها أو عنوانها (ترويسات x-model وx-api-key وx-base-url المهملة، وحقول المزود في مسارات الوسائط)، ويُرفض شكل الترويسات في أزرار اختبار المزودين. والنشر متعدد المستخدمين الذي يتحمّل كل الاستخدام يضبطه عادةً ويقفل الخانات التي يريد تثبيتها.

الأسرار و OPENMAIC_SECRET_KEY Copy Section

• المفاتيح في openmaic.yml تأتي من البيئة عبر ${VAR}. لا تُخزن في قاعدة البيانات ولا تُرسل إلى المتصفح أبدًا.
• المفاتيح التي تدخلها مساحة العمل في إعدادات النماذج تُخزن في قاعدة البيانات مشفرة بـ AES-256-GCM تحت سر المثيل OPENMAIC_SECRET_KEY.
• عندما لا يكون OPENMAIC_SECRET_KEY مضبوطًا، ينشئ الخادم سرًا عشوائيًا عند أول استخدام في data/instance-secret.key (داخل وحدة التخزين openmaic-data مع Docker Compose) ويستخدمه بعد ذلك.

احفظ السر مع نسخ قاعدة البيانات الاحتياطية: المفاتيح المحفوظة تحت سر مفقود أو متغير لا يمكن قراءتها ويجب إدخالها من جديد (تشير إليها إعدادات النماذج). اضبط OPENMAIC_SECRET_KEY صراحةً عندما تتشارك عدة مثيلات قاعدة البيانات نفسها، أو عندما لا يكون للخادم مجلد بيانات دائم (مثل حاوية بلا وحدة تخزين للبيانات)؛ أي سلسلة نصية تصلح، مثل مخرجات openssl rand -base64 32.

من دونه، يعني مجلد البيانات الذي لا يبقى بعد إعادة التشغيل (حاوية بلا وحدة تخزين، أو قرص مؤقت) سرًا جديدًا عند كل تشغيل، وتنشئ كل نسخة من النسخ المتعددة سرها الخاص؛ وفي مجلد عمل للقراءة فقط لا يمكن إنشاء سر ويفشل حفظ المفاتيح في إعدادات النماذج. عند بدء التشغيل يسجّل الخادم تحذيرًا عندما لا يكون OPENMAIC_SECRET_KEY مضبوطًا ومجلد البيانات غير قابل للكتابة، وعندما تحتوي قاعدة البيانات على مفاتيح مختومة بسر غير السر الحالي (مثلًا لفقدان data/instance-secret.key)؛ ويواصل التشغيل مع ذلك.

OPENMAIC_SECRET_KEY=...        # سر المثيل للمفاتيح المحفوظة في إعدادات النماذج
OPENMAIC_CONFIG=/etc/openmaic/openmaic.yml   # اختياري: مسار آخر لـ openmaic.yml

ما يمكن لمساحات العمل إضافته Copy Section

يمكن أن يكون مزودو openmaic.yml أي شيء يقبله المخطط. أما المزودون الذين تضيفهم مساحة العمل في إعدادات النماذج فهم أكثر تقييدًا، لأن عنوانهم ومفتاحهم يكتبهما مستخدم تطبيق الويب:

• لا يُعرض Amazon Bedrock: فهو سيوقّع ببيانات اعتماد AWS الخاصة بالخادم.
• لا proxy ولا أزواج مفاتيح (credentials): الإعدادات المسبقة التي تستخدم زوج مفاتيح، مثل AliDocMind، متاحة للنشر فقط.
• يُسمح بـ baseUrl مخصص فقط للإعدادات المسبقة التي تقدم المحادثة، والمزود الذي يملكه يخدم خانات المحادثة فقط. يجب ألا يحتوي العنوان على بيانات اعتماد أو سلسلة استعلام أو جزء (fragment)، ويجب أن يُحل إلى عنوان عام ما لم يضبط الخادم ALLOW_LOCAL_NETWORKS=true. الطلبات إليه لا تتبع عمليات إعادة التوجيه.
• يجب على خوادم النماذج المحلية (Ollama وLemonade) تسمية عنوانها الخاص بدل localhost الافتراضي في الإعداد المسبق.
• خدمات الوسائط والبحث والمستندات المستضافة ذاتيًا (VoxCPM2 وFunASR وكلام وصور Lemonade وComfyUI وSearXNG وMinerU المستضاف ذاتيًا) تعمل على شبكة الخادم نفسه ومتاحة للنشر فقط.
• لا يُعرض المزودون الذين أوقفهم المشغّل بمتغير <CAP>_<VENDOR>_ENABLED=false القديم.
• لا يمكن لمساحة العمل إعلان معرّف مزود أعلنه openmaic.yml بالفعل.

إذا أراد النشر أن يصل المستخدمون إلى خدمات داخلية، فليعلن هؤلاء المزودين في openmaic.yml.

عملاء API وحقول الطلب المهملة Copy Section

لم تعد طلبات التوليد بحاجة إلى حمل مفاتيح أو اختيارات نماذج: استدعاءات API التي تعمل بلا متصفح، مثل /api/generate-classroom، تُحل عبر الخانات نفسها التي يستخدمها تطبيق الويب، لمساحة عمل المستدعي.

ترويسات الطلب القديمة x-model وx-api-key وx-base-url وx-provider-type وx-model-routes وx-image-provider وx-image-model وx-video-provider وx-video-model، وحقول جسم الطلب المقابلة في مسارات الكلام والبحث والمستندات، مهملة. لا يُعمل بها إلا ما دامت الخانة التي تؤثر فيها بلا تعيين، أو، على خادم لا يزال مُهيأً بالمتغيرات القديمة، بقيمة افتراضية محوَّلة منها فقط (فقد كان DEFAULT_MODEL دائمًا أدنى من النموذج الذي يسميه الطلب)؛ وتغلب القيمة الافتراضية في openmaic.yml واختيار مساحة العمل نفسها والخانة المقفلة، والخانة المضبوطة على null ترفض الطلب أيًا كان ما يسميه. ومع allowUserKeys: false يتم تجاهلها كليًا. يسجّل الخادم تحذيرًا في أول مرة يستخدمها طلب. ستُزال بعد إصدارين فرعيين من صدور إعدادات النماذج الموصوفة أعلاه.

الانتقال من الإعدادات القديمة Copy Section

عندما لا يوجد openmaic.yml، يحوّل الخادم الإعدادات القديمة عند بدء التشغيل ويسجّل إشعار إهمال، وإشعارًا لكل إدخال تعذّر نقله:

عند وجود openmaic.yml تُتجاهل متغيرات المزودين وserver-providers.yml وDEFAULT_MODEL وMODEL_FALLBACK وMODEL_ROUTES في حل النماذج، مع إشعار. ما زال <CAP>_<VENDOR>_ENABLED=false ساريًا؛ لإيقاف قدرة اضبط خانتها على null بدلًا من ذلك.

متغيرات البيئة. قبل:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEFAULT_MODEL=openai:gpt-5.5
MODEL_FALLBACK=anthropic:claude-sonnet-4-6
TTS_MINIMAX_API_KEY=...
TAVILY_API_KEY=tvly-...

بعد (تبقى المفاتيح في البيئة):

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}
  anthropic:
    preset: anthropic
    apiKey: ${ANTHROPIC_API_KEY}
  minimax-tts:
    preset: minimax-tts
    apiKey: ${TTS_MINIMAX_API_KEY}
  tavily:
    preset: tavily
    apiKey: ${TAVILY_API_KEY}

slots:
  llm:
    model: openai:gpt-5.5
    fallback: anthropic:claude-sonnet-4-6
  tts: minimax-tts
  webSearch: tavily

احذف بعد ذلك DEFAULT_MODEL وMODEL_FALLBACK. يمكن إبقاء متغيرات المزودين مصدرًا لإشارات ${VAR}. يصبح _BASE_URL قيمة baseUrl للمزود (OPENAI_BASE_URL ← baseUrl تحت openai؛ اكتب العنوان، أو ${OPENAI_BASE_URL} ما دام المتغير مضبوطًا)، ويصبح _MODELS قائمة models الخاصة به. ومثل DEFAULT_MODEL المحوَّل، فإن llm المكتوب هنا قيمة افتراضية للخادم يمكن لمساحات العمل تغييرها؛ أضف lock: [llm] لتثبيته للجميع. وعلى خلاف التحويل، أصبحت agent تتبع llm: اكتب agent: null لإبقاء وكيل Pro موقوفًا.

server-providers.yml. قبل:

providers:
  azure:
    apiKey: ...
    baseUrl: https://YOUR-RESOURCE.openai.azure.com/openai
    models: [my-deployment]
pdf:
  alidocmind:
    accessKeyId: ...
    accessKeySecret: ...
web-search:
  searxng:
    baseUrl: http://searxng:8080

بعد:

providers:
  azure:
    preset: azure
    apiKey: ${AZURE_OPENAI_API_KEY}
    baseUrl: https://YOUR-RESOURCE.openai.azure.com/openai
    models: [my-deployment]
  alidocmind:
    preset: alidocmind
    credentials:
      accessKeyId: ${ALIDOCMIND_ACCESS_KEY_ID}
      accessKeySecret: ${ALIDOCMIND_ACCESS_KEY_SECRET}
  searxng:
    preset: searxng
    baseUrl: http://searxng:8080

slots:
  llm: azure:my-deployment
  document: alidocmind
  webSearch: searxng

يصبح كل قسم من server-providers.yml مزودين بالإعداد المسبق المطابق (providers ← إعدادات المحادثة، وtts وasr وpdf ← المستندات، وimage وvideo وweb-search)، وينتقل accessKeyId/accessKeySecret إلى credentials.

MODEL_ROUTES. الخادم الذي يضبط MODEL_ROUTES دون openmaic.yml لا يبدأ:

MODEL_ROUTES does not carry over to the model configuration: write the per-stage models as slots in openmaic.yml (or the file named by OPENMAIC_CONFIG) and remove MODEL_ROUTES

لا تتطابق المسارات حسب المرحلة مع الخانات واحدًا لواحد، لذا لا تُحوَّل. أعد كتابة كل مسار كالخانة التي تنتمي إليها مرحلته:

عندما تتشارك عدة مراحل خانة واحدة، أعطِ الخانة النموذج الواحد الذي يجب أن تستخدمه. ينتقل thinking الخاص بالمسار إلى thinking الخانة، وينتقل api وcontextWindow من مسار maic-agent-driver إلى خانة agent. قبل:

DEFAULT_MODEL=openai:gpt-5.5
MODEL_ROUTES='{"scene-outlines-stream":"anthropic:claude-sonnet-4-6","scene-content:slide":{"model":"openai:gpt-5.4","thinking":{"effort":"low"}},"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

بعد:

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}
  anthropic:
    preset: anthropic
    apiKey: ${ANTHROPIC_API_KEY}

slots:
  llm: openai:gpt-5.5
  course.outline: anthropic:claude-sonnet-4-6
  course.content.slide:
    model: openai:gpt-5.4
    thinking: { effort: low }
  agent:
    model: openai:gpt-5.5
    api: openai-completions

بمجرد وجود openmaic.yml لا تضبط متغيرات المزودين وحدها أي شيء: مزود تحويل النص إلى كلام أو الصور أو المستندات أو البحث على الويب الذي لم يكن له سوى متغيراته (TTS_MINIMAX_API_KEY وIMAGE_SEEDREAM_API_KEY وPDF_MINERU_BASE_URL وTAVILY_API_KEY …) لم يعد يُستخدم، ولا تحصل القدرات الأخرى، باستثناء webFetch، على مزود افتراضي. صرّح بكل مزود تستخدمه تحت providers وعيّن tts وimage وdocument وwebSearch (وasr وvideo) في slots، كما في مثال متغيرات البيئة أعلاه؛ وتبقى الخانات الأخرى غير المعيّنة غير مُعدّة ما لم تعيّنها مساحة عمل في إعدادات النماذج.

ثم احذف MODEL_ROUTES وDEFAULT_MODEL وMODEL_FALLBACK.

Docker. اربط الملف بجوار التطبيق وأبقِ المفاتيح في .env.local:

services:
  openmaic:
    volumes:
      - ./openmaic.yml:/app/openmaic.yml:ro

ACCESS_CODE — كلمة مرور على مستوى الموقع Copy Chapter

للنشر المشترك (عروض داخلية، صفوف)، يمكن تعيين رمز وصول ليطلب من الزوار إدخال كلمة مرور قبل رؤية التطبيق:

ACCESS_CODE=your-secret-code

استخدم قيمة عشوائية طويلة (16 حرفًا على الأقل) — فهذا الرمز هو السر الوحيد الذي يحمي النشر. بعد نجاح التحقق، يُحفظ رمز موقَّع في cookie من نوع HTTP-only لمدة 7 أيام، ويُفرض انتهاء صلاحيته من جهة الخادم، لذا يلزم إعادة إدخال الرمز بعد انتهائه. لا يُقيَّد معدل التحقق إلا عند ضبط TRUST_PROXY_HEADERS=true خلف وكيل عكسي موثوق يعيد كتابة x-forwarded-for / x-real-ip: لكل عميل 10 محاولات كل 60 ثانية، ونجاح التحقق يمسح عدّاد ذلك العميل. وبدون وكيل موثوق لا يستطيع التطبيق نسبة الطلب إلى عميل بعينه، لذا لا يوجد أي تقييد، وتكون الحماية في طول الرمز وعشوائيته. اتركه فارغًا لتعطيله.

feature flags (مفاتيح الميزات) Copy Chapter

تُعتبر القيم true أو 1 مفعلة، وما لم يُذكر خلاف ذلك تُعد أي قيمة أخرى معطلة. تُحقن متغيرات NEXT_PUBLIC_* في وقت البناء للعميل، ويجب إعادة البناء بعد تعديلها:

# محرر MAIC (وضع Pro)
NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true

# مراجع مواد PPT والمشاهد التفاعلية أثناء تشغيل Pi (علامة وقت البناء؛ لا تؤثر في مراجع وضع التحرير)
NEXT_PUBLIC_COURSEWARE_REFERENCE_ENABLED=true

# محرك مهام التعليم المهني (مفتاح خادم)
OPENMAIC_ENABLE_VOCATIONAL=true

# عرض مفتاح تجربة التعليم المهني
NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI=true

# عرض مدخل تصدير الفيديو
NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true

# عرض مدخل استيراد PPTX التجريبي
NEXT_PUBLIC_ENABLE_PPTX_IMPORT=true

تعمل محادثة الصف دائمًا على Pi، وتتطلب نموذجًا يدعم استدعاء الأدوات/الدوال: اختر نموذجًا كهذا لـ الصف في إعداد نماذج المقرر، أو اضبط الخانة classroom (أو الخانة llm التي ترث منها) في openmaic.yml. مع Gemini استخدم الإعداد المسبق الأصلي google بدلًا من عنوان Google المتوافق مع OpenAI. يُرفض النموذج الذي يذكر الكتالوج المدمج أنه لا يدعم استدعاء الأدوات قبل الاستدلال، مع 400 MODEL_CONFIG_INVALID (reason: tool_calling_required)، ويشير إعداد نماذج المقرر إلى هذا الشرط عند خانة الصف.

أُزيلت محادثة الصف القديمة المبنية على director-graph، ولم يعد NEXT_PUBLIC_PI_CHAT_ENABLED يختار مسار المحادثة. احذف هذا المتغير من إعداداتك: لا يقبل بناء production إلا ترك المتغير غير مضبوط، أو سلسلة فارغة، أو true، أو 1 (مطابقة تامة)، ويفشل مع إرشادات الانتقال عند أي قيمة أخرى. في Docker Compose، يوفّر env_file الخاص بالخدمة (.env.local) قيم وقت التشغيل، لا وسائط البناء.

استيراد PPTX لا يزال تجريبيًا، والنتائج لم تُدمج بالكامل في تدفق بيانات الصف. جميع متغيرات NEXT_PUBLIC_* هي مفاتيح بناء؛ عند نشر Docker، يجب تمريرها كـ build args، لا يمكن فقط تعيينها في بيئة الحاوية.

خيارات خادم أخرى Copy Chapter

يمكن تكوين الخيارات التالية عبر متغيرات البيئة:

# توليد متوازي لمحتوى المشاهد؛ 0 أو عدم التعيين يعني توليد تسلسلي
PARALLEL_SCENE_CONCURRENCY=3

# السماح بالوصول إلى localhost والشبكات المحلية؛ فقط للنشر الذاتي/الشبكات الداخلية
ALLOW_LOCAL_NETWORKS=true

# خدمة تصيير MP4 اختيارية
RENDER_SERVICE_URL=http://render-service:9000

# إعدادات السجلات والتفكير
LOG_LEVEL=info
LOG_FORMAT=pretty
LLM_THINKING_DISABLED=false

متغيرات بيئة المزودين القديمة Copy Chapter

هذه المتغيرات وserver-providers.yml هي إعدادات الإصدارات السابقة. ما زالت تعمل عند عدم وجود openmaic.yml (راجع الانتقال من الإعدادات القديمة)، لكنها مهملة وستُزال بعد إصدارين فرعيين من صدور إعدادات النماذج. مع openmaic.yml استخدمها فقط مصدرًا لإشارات ${VAR}. يشرح قسم الانتقال DEFAULT_MODEL وMODEL_FALLBACK؛ ولم يعد MODEL_ROUTES يُقرأ.

موفرو LLM Copy Section

عادةً ما يستخدم موفرو السحابة ثلاثة متغيرات بيئة: مفتاح API، عنوان URL الأساسي، وقائمة النماذج. مفتاح API عادةً مطلوب، أما العنوان الأساسي وقائمة النماذج فاختياريان. Azure OpenAI يحتاج إلى تكوين نقطة نهاية المورد، بينما Ollama وLemonade لا يحتاجان إلى مفتاح API.

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=                # تجاوز اختياري للعنوان الأساسي
OPENAI_MODELS=                  # قائمة بيضاء اختيارية للنماذج (مفصولة بفواصل)

بادئات الموفرين المدعومة:

يستخدم Azure OpenAI اسم النشر كمعرف للنموذج:

AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_BASE_URL=https://YOUR-RESOURCE.openai.azure.com/openai
AZURE_OPENAI_MODELS=your-deployment-name

للاتصال بخدمة LLM أخرى متوافقة مع OpenAI، أعلن في openmaic.yml مزودًا من نوع openai-compatible مع baseUrl وmodels الخاصة به، أو أضفه عبر إضافة مزود ضمن الإعدادات ← خدمات النماذج ← نماذج اللغة.

للتفاعل مع Gemini في الصف، استخدم الإعداد المسبق الأصلي google: أضف Google في الإعدادات ← خدمات النماذج ثم اختره لـ الصف في إعداد نماذج المقرر. يرفض Pi مبكرًا عنوان Google الرسمي المتوافق مع OpenAI (https://generativelanguage.googleapis.com/v1beta/openai) ويعرض إرشادات الانتقال؛ تُتابَع مسألة استدعاء الأدوات عبر المسار المتوافق في #1556. يتعرف هذا الفحص على ذلك العنوان الرسمي فقط ولا يحدد المزود خلف بوابات الجهات الخارجية.

النماذج المحلية (Ollama و Lemonade) Copy Section

لا تحتاج Ollama وLemonade إلى مفتاح API؛ يجب كتابة عنوان URL الأساسي للخدمة المحلية في إعدادات الخادم لتجاوز فحص SSRF:

OLLAMA_BASE_URL=http://localhost:11434/v1
# LEMONADE_BASE_URL=http://localhost:13305/v1

يمكن تحديد قائمة بيضاء للنماذج المتاحة باستخدام OLLAMA_MODELS أو LEMONADE_MODELS.

موفرو TTS Copy Section

يستخدم موفرو TTS على الخادم متغيرات TTS__API_KEY، مع خيار TTS__BASE_URL للتجاوز.

# Doubao TTS (Volcengine Seed-TTS، MP3 أصلي)
TTS_DOUBAO_API_KEY=appId:accessKey
TTS_DOUBAO_BASE_URL=       # تجاوز اختياري

# Qwen TTS
TTS_QWEN_API_KEY=
TTS_QWEN_BASE_URL=         # تجاوز اختياري

# أي نقطة نهاية متوافقة مع OpenAI TTS
TTS_OPENAI_API_KEY=
TTS_OPENAI_BASE_URL=

# VoxCPM2 (TTS ذاتي الاستضافة مع استنساخ الصوت، راجع صفحة VoxCPM2)
TTS_VOXCPM_BASE_URL=http://localhost:8000

بادئات TTS المدعومة تشمل TTS_OPENAI_، TTS_AZURE_، TTS_GLM_، TTS_QWEN_، TTS_MINIMAX_، TTS_DOUBAO_، TTS_ELEVENLABS_، TTS_GOOGLE_، TTS_VOXCPM_ و TTS_LEMONADE_. TTS المحلي لـ Lemonade وVoxCPM2 لا يحتاجان إلى مفتاح API. TTS المدمج في المتصفح لا يحتاج إلى إعدادات خادم.

يمكن للمسؤولين تعطيل موفر TTS معين على الخادم باستخدام TTS__ENABLED=false. لمزيد من التفاصيل عن VoxCPM2 (TTS ذاتي الاستضافة واستنساخ الصوت)، راجع الفصل الخاص بـ VoxCPM2.

لاستخدام عنوان TTS آخر متوافق مع OpenAI، أعلن في openmaic.yml مزودًا من نوع openai-tts بذلك baseUrl وعيّن له خانة tts. لا يمكن لمساحات العمل إضافة عناوين TTS مخصصة في إعدادات النماذج.

ASR (تحويل الكلام إلى نص) Copy Section

# OpenAI Whisper
ASR_OPENAI_API_KEY=
ASR_OPENAI_BASE_URL=       # تجاوز اختياري

# Qwen ASR
ASR_QWEN_API_KEY=
ASR_QWEN_BASE_URL=         # تجاوز اختياري

# Azure ASR
ASR_AZURE_API_KEY=
ASR_AZURE_BASE_URL=https://{region}.api.cognitive.microsoft.com

# FunASR (محلي، لا يحتاج إلى مفتاح)
ASR_FUNASR_BASE_URL=http://localhost:8000/v1

# Lemonade ASR (محلي، لا يحتاج إلى مفتاح)
ASR_LEMONADE_BASE_URL=http://localhost:13305/v1

شغّل خدمة FunASR المتوافقة مع OpenAI باستخدام funasr-server --device cuda. تستقبل ملفات WAV على /v1/audio/transcriptions وتدعم SenseVoiceSmall وParaformer وFun-ASR-Nano.

ASR المدمج في المتصفح لا يحتاج إلى إعدادات خادم.

لاستخدام عنوان ASR آخر متوافق مع OpenAI، أعلنه في openmaic.yml بالإعداد المسبق openai-whisper وbaseUrl الخاص به، وعيّن له خانة asr. لا يمكن لمساحات العمل إضافة عناوين ASR مخصصة في إعدادات النماذج:

providers:
  my-asr:
    preset: openai-whisper
    apiKey: ${MY_ASR_API_KEY}
    baseUrl: https://asr.example.com/v1

slots:
  asr: my-asr:whisper-1

موفرو توليد الصور Copy Section

يستخدم موفرو الصور متغيرات IMAGE__API_KEY، مع خيار IMAGE__BASE_URL. البادئات المدعومة تشمل:

IMAGE_OPENAI_، IMAGE_SEEDREAM_، IMAGE_QWEN_IMAGE_، IMAGE_NANO_BANANA_، IMAGE_MINIMAX_، IMAGE_GROK_، IMAGE_GLM_ و IMAGE_LEMONADE_.

يولّد GLM Image (Zhipu CogView) الصور بنماذج CogView (cogview-3-flash وcogview-4):

providers:
  glm-image-service:
    preset: glm-image
    apiKey: ${IMAGE_GLM_API_KEY}
    # اختياري:
    baseUrl: https://open.bigmodel.cn/api/paas/v4

slots:
  image: glm-image-service:cogview-3-flash

أو اضبطه عبر متغيرات البيئة:

IMAGE_GLM_API_KEY=
# اختياري:
IMAGE_GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4

Lemonade خدمة محلية ولا تحتاج إلى مفتاح API:

IMAGE_LEMONADE_BASE_URL=http://localhost:13305/v1

لا يحتاج ComfyUI Image إلى مفتاح API. يعمل على شبكتك الخاصة، لذا يضبطه النشر: أعلنه في openmaic.yml بعنوان خادم ComfyUI وعيّن له خانة image.

providers:
  comfyui:
    preset: comfyui-image
    baseUrl: http://host.docker.internal:8188

slots:
  image: comfyui

ضع ملفات JSON لسير العمل المصدّرة بصيغة API في مجلد public/ الخاص بـ OpenMAIC. يجب أن تطابق أسماء الملفات comfyui-*.json أو تحتوي على workflow؛ يكتشف OpenMAIC هذه الملفات تلقائيًا ويعرضها كسير عمل. مع Docker، أضف سير العمل قبل بناء الصورة أو اربط ملف سير عمل منفردًا في /app/public/ داخل الحاوية. بما أن المزود مُعلن من النشر، فلا يحتاج خادم ComfyUI على المضيف أو على شبكة خاصة إلى ALLOW_LOCAL_NETWORKS.

موفرو توليد الفيديو Copy Section

يستخدم موفرو الفيديو متغيرات VIDEO__API_KEY، مع خيار VIDEO__BASE_URL. البادئات المدعومة تشمل:

VIDEO_SEEDANCE_، VIDEO_KLING_، VIDEO_SORA_، VIDEO_MINIMAX_، VIDEO_GROK_ و VIDEO_HAPPYHORSE_.

تحليل المستندات والوسائط Copy Section

تعتمد صيغ المواد التعليمية على المحلل المختار. حاليًا يدعم النصوص، PDF، مستندات Office، الصور، وبعض صيغ الصوت والفيديو؛ تختلف الصيغ المدعومة والقدرات حسب الموفر.

# MinerU ذاتي الاستضافة
PDF_MINERU_BASE_URL=http://localhost:8888

# MinerU backend اختياري ذاتي الاستضافة
PDF_MINERU_BACKEND=pipeline

# MinerU Cloud
PDF_MINERU_CLOUD_API_KEY=
PDF_MINERU_CLOUD_BASE_URL=https://mineru.net/api/v4

# AliDocMind (يستخدم AccessKey من Alibaba Cloud بدلاً من مفتاح API منفصل)
ALIDOCMIND_ACCESS_KEY_ID=
ALIDOCMIND_ACCESS_KEY_SECRET=
ALIDOCMIND_BASE_URL=       # تجاوز اختياري

unpdf مدمج في OpenMAIC ويستخدم لتحليل PDF الأساسي. لتحليل مستندات Office، الصور، أو المواد التي تحتاج إلى OCR، جداول، معادلات أو تحليل تخطيط، يجب اختيار موفر MinerU أو AliDocMind المتوافق.

يدعم AliDocMind تحليل PDF، DOCX، PPTX، XLSX، بالإضافة إلى PNG، JPG/JPEG، BMP، GIF. حاليًا، يدعم تحليل الوسائط الصوتية والفيديو فقط عبر AliDocMind: صيغ الفيديو MP4، MOV، AVI، MKV، WMV، وصيغ الصوت MP3، WAV، AAC؛ لا يدعم M4A.

البحث عبر الإنترنت Copy Section

اضبط موفري البحث Tavily، Exa، Firecrawl، Bocha، Brave، Baidu، SearXNG أو MiniMax:

TAVILY_API_KEY=
TAVILY_BASE_URL=           # تجاوز اختياري

EXA_API_KEY=
EXA_BASE_URL=https://api.exa.ai  # تجاوز اختياري

FIRECRAWL_API_KEY=
FIRECRAWL_BASE_URL=https://api.firecrawl.dev  # تجاوز اختياري

BOCHA_API_KEY=
BOCHA_BASE_URL=            # تجاوز اختياري

BAIDU_API_KEY=
BAIDU_BASE_URL=https://qianfan.baidubce.com  # تجاوز اختياري

# SearXNG ذاتي الاستضافة، لا يحتاج إلى مفتاح API
SEARXNG_BASE_URL=

WEB_SEARCH_MINIMAX_API_KEY=
WEB_SEARCH_MINIMAX_BASE_URL=https://api.minimaxi.com  # تجاوز اختياري

لا يحتاج Brave وSearXNG إلى مفتاح API. لا يوجد مفتاح للبحث على الويب في كل عملية توليد: يعمل متى حُلت خانة webSearch لمساحة العمل، وإيقافه (webSearch: null في openmaic.yml، أو بمفتاح البحث في الإعدادات ← إعدادات نماذج الدورة) يؤثر في عمليات التوليد اللاحقة لتلك المساحة. يُقدَّم البحث على الويب في Grok عبر أداة البحث في Grok LLM، وليس مزود بحث مستقلًا.

server-providers.yml Copy Section

مهمل لصالح openmaic.yml. عند وجود الملفين معًا، يضبط openmaic.yml وحده النماذج.

بدلاً من متغيرات البيئة، يمكنك وضع إعدادات موفري الخادم المسجلين في الكود داخل ملف server-providers.yml في جذر المشروع. يُحمّل الملف عند بدء الخادم، والبنية تطابق تصنيفات متغيرات البيئة:

providers:
  openai:
    apiKey: sk-...
    baseUrl: https://api.openai.com/v1
    models:
      - gpt-5.5
  anthropic:
    apiKey: sk-ant-...

tts:
  doubao-tts:
    apiKey: appId:accessKey

asr:
  openai-whisper:
    apiKey: sk-...

pdf:
  mineru:
    baseUrl: http://localhost:8888
  alidocmind:
    accessKeyId: your-access-key-id
    accessKeySecret: your-access-key-secret

image:
  seedream:
    apiKey: ...

video:
  seedance:
    apiKey: ...

web-search:
  tavily:
    apiKey: tvly-...
  exa:
    apiKey: ...
  firecrawl:
    apiKey: fc-...
  searxng:
    baseUrl: http://localhost:8080

تتجاوز متغيرات البيئة حقول YAML المطابقة حقلًا بحقل. يجب أن تستخدم المفاتيح معرفات الموفرين المسجلين في الكود مثل openai، doubao-tts، openai-whisper، mineru، alidocmind، seedream، seedance، exa، tavily أو searxng. لا يمكن تسجيل معرفات غير معروفة هنا كموفري LLM مخصصين.

تفويض النماذج لدى المزودين المدارين من الخادم Copy Chapter

للمزودين الذين يرسلون النموذج المختار إلى الخدمة الأصلية باستخدام بيانات اعتماد النشر، اضبط قائمة models صريحة في openmaic.yml (providers..models)، أو متغير البيئة *_MODELS المقابل / قائمة models في قسم server-providers.yml. ينطبق ذلك على المحادثة والصور والفيديو وتحويل النص إلى كلام والتعرف على الكلام والبحث على الويب المعتمد على النماذج. تُطابَق معرّفات النماذج مطابقة تامة، مع مراعاة حالة الأحرف، بعد إزالة المسافات المحيطة عند تحميل الإعدادات. تُفوَّض الأسماء المستعارة الحتمية للمحوّلات بمعرّف النموذج المُعلَن. تُعيد طلبات النماذج غير المدرجة HTTP 403 مع PROVIDER_DISABLED والرسالة «This model is not authorized for server-managed credentials».

تغيير كاسر: من دون قائمة صريحة، لا يمكن استخدام إلا النماذج الافتراضية والاحتياطية للنشر، والنماذج الأساسية والاحتياطية التي تشير إليها خانات تلك القدرة. في الإعدادات القديمة، يفوّض DEFAULT_MODEL وMODEL_FALLBACK نماذج المحادثة. خانة الوسائط التي تذكر المزود فقط تفوّض النموذج الافتراضي الوحيد للمحوّل، ولا تفوّض كتالوج الإعداد المسبق كله. لا يمكن لتعيينات مساحة العمل توسيع المجموعة المفوَّضة في النشر. ويجب أن يفوّض تسجيل الأصوات وتوليفها أيضًا أي نموذج يُختار لتوافق الصوت.

للانتقال، اذكر كل نموذج ينبغي أن يتمكن المستخدمون من اختياره، وأعد تشغيل الخادم، وحدّث اختيارات مساحات العمل التي لم تعد مفوَّضة. تذكر سجلات التشغيل الإعداد الواجب إضافته لكل مزود لديه بيانات اعتماد بلا قائمة. لا تتأثر بيانات اعتماد المستخدمين الخاصة بمزوديهم، ولا المزودون المحليون الذين لا يحتاجون إلى مفتاح مثل Ollama وLemonade. المزود المضبوط دون بيانات اعتماد غير مقيَّد، فلا توجّهه إلى بوابة تضيف بيانات اعتماد خاصة بها نحو الخدمة الأصلية (مثل وكيل داخلي متوافق مع OpenAI): أعطِ تلك البوابة مفتاحًا واضبطها مزودًا ببيانات اعتماد وقائمة models، أو قيّد النماذج في البوابة نفسها. لا تحتاج محللات المستندات وخدمات البحث التي لا تختار نموذجًا (مثل Tavily) إلى قائمة نماذج.

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}
    models: [gpt-5.4-mini]
slots:
  llm: openai:gpt-5.4-mini

المكافئ في الإعدادات القديمة: OPENAI_API_KEY=... وOPENAI_MODELS=gpt-5.4-mini. للوسائط استخدم بادئة القدرة، مثل IMAGE_SEEDREAM_MODELS وVIDEO_SEEDANCE_MODELS وTTS_OPENAI_MODELS وASR_OPENAI_MODELS وWEB_SEARCH_CLAUDE_MODELS.

البحث وجلب الصفحات باستخدام DeepSeek Copy Section

يشترك الإعداد deepseek في DEEPSEEK_API_KEY وعنوان API الأساسي بين المحادثة والبحث واستخراج Markdown المستضاف. يستخدم البحث POST /v1/tools/search ويعيد حتى 50 نتيجة، ويقتطع الاستعلام إلى 128 نقطة ترميز Unicode. يستخدم summary ثم snippet عند فراغه. يستخدم الجلب POST /v1/tools/fetch ويقرأ content وtitle الاختياري غير الفارغ.

في الإعدادات القديمة، فعّل WEB_SEARCH_DEEPSEEK_ENABLED=true أو أضف web-search.deepseek صراحةً إلى server-providers.yml. بيانات اعتماد المحادثة وحدها لا تفعّل البحث ولا تستبدل مزود البحث الافتراضي الحالي. يعطّل WEB_SEARCH_DEEPSEEK_ENABLED=false البحث قسرًا. عند وجود openmaic.yml لا يستطيع المتغير القديم تعيين خانة؛ أعلن المزود وعيّن webSearch و/أو webFetch صراحةً.

The default API base is https://api.deepseek.com/v1. On api.deepseek.com, every base path (including /beta) is normalized to /v1 before appending /tools/search or /tools/fetch. Custom gateway bases preserve their configured path prefix; a bare root gets /v1 first. Custom endpoints belong in deployment configuration, while client and workspace overrides remain restricted to official endpoints. The default fetch reader remains builtin. See DeepSeek official pricing for current request charges. Failed requests and searches with no results are not billed.

providers:
  deepseek:
    preset: deepseek
    apiKey: ${DEEPSEEK_API_KEY}
    baseUrl: https://api.deepseek.com/v1
slots:
  webSearch: deepseek
  webFetch: deepseek

محادثة Kimi والبحث على الويب Copy Section

أعلن حساب Kimi واحدًا وعيّن له الخانتين:

providers:
  kimi:
    preset: kimi
    apiKey: ${KIMI_API_KEY}
    # اختياري: https://api.moonshot.ai/v1 للمنصة المفتوحة الدولية.
    # baseUrl: https://api.moonshot.ai/v1
slots:
  llm: kimi:kimi-k3
  webSearch: kimi

لمفتاح Coding Plan، استخدم preset: kimi-coding-plan وllm: kimi:kimi-for-coding؛ عنوانه الأساسي الافتراضي هو https://api.kimi.com/coding/v1. يجب إقران مفاتيح المنصة المفتوحة وCoding Plan بالعناوين الأساسية المطابقة لها. في الإعدادات القديمة، لا يوفّر KIMI_API_KEY وKIMI_BASE_URL الاختياري بيانات اعتماد البحث إلا بعد التفعيل الصريح: اضبط WEB_SEARCH_KIMI_ENABLED=true أو أضف web-search.kimi في server-providers.yml (مثلًا مع enabled: true). لا تفعّل بيانات اعتماد المحادثة وحدها البحث ولا تغيّر مزود البحث الافتراضي. يعطّل WEB_SEARCH_KIMI_ENABLED=false بحث Kimi حتى عند تعيين خانة له. WEB_SEARCH_KIMI_ENABLED هو المفتاح الوحيد لبحث Kimi. ينطبق KIMI_MODELS على المحادثة فقط. عند تعارض حسابَي المحادثة والبحث في الإعدادات القديمة، يظهر تحذير ويُتخطّى إدخال البحث؛ أعلن معرّفات مزودين منفصلة في openmaic.yml عند الحاجة إلى حسابات منفصلة. عند وجود openmaic.yml، أعلن المزود وعيّن الخانات صراحةً. تتيح الإعدادات ومعالج التشغيل الأول استخدام القدرتين من الحساب نفسه.

يعتمد اختيار نقطة النهاية على المسار الأساسي: بعد إزالة الشرطات المائلة الختامية، يستخدم المسار المنتهي بـ /coding/v1 نقطة /search، وتستخدم المسارات الأخرى /tools/search_pro. يجب أن تحافظ الوكلاء المخصصة المضبوطة في النشر على بنية المسار هذه. يوصي المعالج بالبحث لعناوين الحسابات الرسمية فقط، لذلك لا يحصل وكيل المحادثة المخصص لمساحة العمل على تعيين بحث تلقائيًا.

عند وجود openmaic.yml، أعلن providers.: { preset: kimi } وعيّن slots.webSearch: ؛ لا يستطيع المتغير القديم WEB_SEARCH_KIMI_ENABLED تعيين هذه الخانة.

خانة مزوّد جلب صفحات الويب Copy Chapter

تحدد webFetch خدمة القراءة التي تستخدمها أداة الوكيل fetch_url. الخدمة الافتراضية هي builtin في الإعدادات القديمة والفارغة وملفات YAML، حتى عند عدم تحديد هذه الخانة تحت lock: all. يؤدي ضبط webFetch: null صراحةً إلى تعطيل الجلب وإزالة الأداة وتعليماتها من عمليات التشغيل اللاحقة. يستخدم كل طلب مزوّدًا واحدًا دون مزوّد احتياطي أو تصعيد إلى خدمة أخرى. تؤدي الإشارة غير الصالحة إلى مزوّد أو عنوان خدمة في مساحة العمل ترفضه السياسة إلى فشل تشغيل الوكيل بالكامل أثناء تحديد الإمكانات، قبل بدء الوكيل، كما في webSearch. هذا خطأ في الإعدادات وليس نتيجة فشل من fetch_url، ولا يتم الانتقال إلى القارئ المدمج.

providers:
  reader:
    preset: kimi
    apiKey: ${KIMI_API_KEY}
    baseUrl: https://api.moonshot.cn/v1
slots:
  webFetch: reader

يوفر كلا الإعدادين المسبقين kimi وkimi-coding-plan قدرة webFetch. لبيانات اعتماد Coding Plan، استخدم preset: kimi-coding-plan؛ وعنوانه الأساسي الافتراضي هو https://api.kimi.com/coding/v1. يُحافظ على أي عنوان أساسي مضبوط صراحةً. تستخدم عناوين Moonshot Open Platform (https://api.moonshot.cn/v1 وhttps://api.moonshot.ai/v1) المسار /tools/fetch، بينما يستخدم Coding Plan المسار /fetch. يرسل كلاهما طلب POST يحتوي على { "url": ... } مع مصادقة Bearer. يقبل المهايئ markdown أو content. اختبر أحد المشرفين POST https://api.kimi.com/coding/v1/fetch باستخدام مفتاح فعلي وأكد الاستجابة { markdown, title, url }؛ لا يزال توافر العناوين الدولية غير متحقق منه. تراعي الطلبات إعداد proxy الخاص بالمزوّد ومتغيرات بيئة الوكيل القياسية.

يوفر DeepSeek أيضًا استخراج Markdown المستضاف عبر الإعداد deepseek مع إعادة استخدام مفتاح المحادثة وعنوان API الأساسي. عيّن webFetch صراحةً كما في المثال أعلاه. يستخدم /v1/tools/fetch ويحفظ عنوان البوابة المضبوط في النشر. المهل الزمنية وإعادة المحاولة مرة واحدة لأخطاء النقل فقط مماثلة لـ Kimi، دون إعادة أخطاء HTTP أو الاستجابات غير الصالحة.

استخدم بيانات الاعتماد الحالية في الإعدادات ← خدمات النماذج ← جلب صفحات الويب، واختر القارئ في إعداد نماذج المقرر ← جلب صفحات الويب. يُستخدم المفتاح نفسه للدردشة مع هذا المزوّد؛ تغييره أو حذفه يؤثر في الدردشة أيضًا. تكون البطاقة للقراءة فقط عندما يثبّتها المسؤول. يحتفظ الإعداد الأولي بالقارئ المدمج حتى اختيار قارئ آخر صراحةً. يمكن لبيانات اعتماد مساحة العمل استخدام عناوين API الأساسية الرسمية؛ أما عناوين الجلب المخصصة والوكلاء فيجب أن يعلنها المسؤول في openmaic.yml.

بخلاف kimi، يستخدم firecrawl مفتاحًا خاصًا به: عرّف مزوّدًا بالإعداد preset: firecrawl والمفتاح apiKey (مثل ${FIRECRAWL_API_KEY})، أو أدخل المفتاح في الإعدادات ← خدمات النماذج ← جلب صفحات الويب. يرسل الطلب POST /v2/scrape بمصادقة Bearer ويطلب المحتوى الرئيسي للصفحة بصيغة Markdown. العنوان الأساسي الافتراضي هو https://api.firecrawl.dev؛ ويجب أن يعرّف المسؤول العنوان الأساسي لخادم Firecrawl المستضاف ذاتيًا في openmaic.yml.

يخدم مزوّد firecrawl نفسه البحث على الويب أيضًا (POST /v2/search): مفتاح واحد وعنوان أساسي واحد يكفيان للأمرين، لذا يمكن تعيين مزوّد واحد في slots.webSearch وslots.webFetch معًا. تضبط المتغيرات القديمة FIRECRAWL_API_KEY وFIRECRAWL_BASE_URL هذا المزوّد نفسه، ويبقى جلب صفحات الويب على builtin إلى أن يُعيَّن webFetch له.

قبل إرسال رابط إلى خدمة مستضافة، تُطبق بوابة روابط الجلسة والتطبيع الصارم للرابط وفحص جميع عناوين DNS المحلية. تُطبق الفحوص نفسها على الرابط النهائي الذي تعيده الخدمة قبل قبول المحتوى. تتحكم الخدمات المستضافة في DNS والتحويلات الوسيطة الخاصة بها، لذلك لا تستطيع الفحوص المحلية تثبيت اتصالاتها الشبكية. يظل النص بيانات غير موثوقة، ويخضع لاكتشاف صفحات التحقق وحدود الحجم بالبايت وعلامة الاقتطاع، مع حفظ مواد الويب وصيغة النتيجة {trusted, untrusted} كما في السابق.

Packages Docs Content Docs Configuration.Ja (`packages/docs/content/docs/configuration.ja.mdx`) Copy Section

title: 設定 Copy Chapter

OpenMAIC には 3 つの設定ソースがあり、それぞれが 1 つの役割だけを担います。

DATABASE_URL is required; other environment variables are optional (see Deployment). Providers that use server credentials for model selection also need authorized model lists, as described below. See .env.example for environment variables, openmaic.example.yml for a sample model configuration, and Supported models for preset and model IDs.

以前のリリースでは、モデルはプロバイダー環境変数、server-providers.yml、DEFAULT_MODEL、MODEL_ROUTES でしか設定できませんでした。MODEL_ROUTES を除き、これらは現在も動作しますが非推奨です。旧設定からの移行を参照してください。

モデルとプロバイダー Copy Chapter

基本概念 Copy Section

• プロバイダー（provider）：サーバーが呼び出せる 1 つのアカウント。たとえば OpenAI のキー、MiniMax の Token Plan、セルフホストの OpenAI 互換サーバーなど。各プロバイダーには自分で決める ID と、どのベンダーでどの機能をカバーするかを示すプリセット（preset）があります。
• スロット（slot）：製品の中で AI を使う箇所。たとえばコースのアウトライン、スライドの内容、音声合成、Web 検索など。スロットは機能ごとに 1 本の木を構成し、割り当てのないスロットは親スロットに従います。
• 割り当て（assignment）：スロットが使うプロバイダーとモデル（provider:model）。呼び出しパラメーターとフォールバックモデルを付けることもでき、null でスロットを無効にできます。

機能が使えるかどうかは、そのスロットが割り当てに解決されるかどうかだけで決まります。別のオン／オフスイッチはありません。

openmaic.yml Copy Section

サーバーは起動ディレクトリ（リポジトリのルート。Docker イメージでは /app）から openmaic.yml を読み込みます。別のパスを使うには OPENMAIC_CONFIG を設定します。相対パスは同じディレクトリを基準に解決され、この場合ファイルは必ず存在しなければなりません。ファイルがない場合、サーバーは Web アプリの設定と、まだ設定されている旧来の変数を使います。

ファイルは起動時に一度だけ読み込まれるため、変更後はサーバーを再起動してください。サーバーは起動前にファイル全体を検証します。未設定の ${VAR}、不明なプリセットやスロット、宣言されていないプロバイダーへの参照、スロットの機能を提供しないプロバイダーがあるとサーバーは起動せず、問題ごとにその場所が表示されます。

[boot] Invalid server configuration; the server will not start: Invalid model configuration in /app/openmaic.yml:
  - providers.openai.apiKey: environment variable OPENAI_API_KEY is not set
  - slots.course.outlines: unknown slot

シークレットはファイルに直接書かず、${VAR} で参照して環境変数に設定してください。環境変数から来た値はこれらのメッセージに表示されません。

完全な例 Copy Section

providers:
  # <プロバイダー ID>：小文字、数字、ハイフン
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}      # 起動時に環境変数から読み込む
  anthropic:
    preset: anthropic
    apiKey: ${ANTHROPIC_API_KEY}
  openai-image:                    # 同じキーを画像生成に使う
    preset: openai-image
    apiKey: ${OPENAI_API_KEY}
  minimax:                         # Token Plan：チャット、画像、動画、TTS、検索
    preset: minimax
    apiKey: ${MINIMAX_API_KEY}
  tavily:
    preset: tavily
    apiKey: ${TAVILY_API_KEY}
  local:                           # 任意の OpenAI 互換サーバー
    preset: openai-compatible
    baseUrl: http://ollama:11434/v1
    models: [qwen3:8b]

slots:
  llm: openai:gpt-5.5              # 以下のすべてのチャットスロットの既定値
  course.outline:
    model: anthropic:claude-sonnet-4-6
    fallback: openai:gpt-5.4-mini  # 再試行可能な失敗時に一度だけ使う
  course.content.slide:
    model: minimax:MiniMax-M3
    thinking: { enabled: false }
    fallback: minimax:MiniMax-M2.7
  classroom: local:qwen3:8b        # モデル ID にコロンを含めてよい
  agent:
    model: openai:gpt-5.5          # ツール呼び出しが必要
    api: openai-completions
  tts: minimax:speech-2.8-turbo
  image: openai-image:gpt-image-2
  webSearch: tavily                # プロバイダーのみ：その既定モデル
  video: null                      # 既定では無効。ユーザーが有効にできる

lock: [tts]                        # サブツリーごと全員に対して固定
allowUserKeys: false               # ユーザーはこれらのプロバイダーから選ぶだけで、追加はできない

このファイルでは、slots に書いたスロットはサーバーの既定値です。ユーザーはモデル設定でそれぞれ変更できますが、lock で固定した tts だけは全員に対して変更できません。記載していないチャットスロット（例：course.agents）は親（llm）に従い、記載していない機能のルート（例：asr や document）はユーザーが割り当てるまで未設定のままです。allowUserKeys: false の場合、ユーザーはここで宣言したプロバイダーの中からのみ選びます。

プロバイダー Copy Section

providers の各エントリが 1 つのプロバイダーを宣言します。キーがその ID で、スロットからの参照に使います。1〜63 文字の小文字・数字・ハイフンで、先頭は英字か数字です。

ほとんどのプリセットは組み込みレジストリに対応し、1 つの機能だけをカバーします。openai プリセットはチャットのみで、OpenAI の画像・音声合成・文字起こしはそれぞれ openai-image、openai-tts、openai-whisper プリセットです。機能ごとにプロバイダーを 1 つ宣言し、1 つのキーで複数の機能を使う場合は同じ ${VAR} を参照してください。Token Plan プリセット（minimax、tokendance、volcengine-ark、kimi-coding-plan）は 1 つのキーで複数の機能をカバーし、各機能はプラン独自のエンドポイントを使います。プロバイダーに設定した baseUrl は、そのプロバイダーがカバーするすべての機能のエンドポイントを置き換えるため、Token Plan に baseUrl を設定するのは全機能が一緒に移る場合だけにしてください。

Amazon Bedrock（preset: bedrock）はサーバーの AWS 認証情報チェーン（環境変数、プロファイル、ロール）でリクエストに署名し、リージョンは BEDROCK_REGION、AWS_REGION、AWS_DEFAULT_REGION から読み取ります。apiKey は任意のベアラートークンです。

スロット Copy Section

スロットの解決方法：

• 呼び出し元のスロットから機能のルートへ向かって上にたどり、最初に見つかった割り当てが使われます。つまり親の割り当てがそのサブツリー全体の既定値になり、親を変えると自分の割り当てを持たない子もすべて変わります。
• ロックされたサブツリーの中（そのスロットか祖先が lock に挙げられている、または lock: all）では openmaic.yml だけが参照されます。ロックされたスロットまで上にたどり、ファイルに書かれた最初の割り当てが使われます。それ以外ではユーザーの選択が優先されます。まずスロットからルートまでワークスペース自身の割り当てを探し、一つもない場合にだけ、同じくスロットから上へ openmaic.yml の既定値を探します。そのため、ワークスペースが親を設定していれば、子にサーバーの既定値が書かれていても、ワークスペースが変更していない子は親に従います。サーバーの値はあくまで既定値です。
• null はそこで探索を止めます。そのスロットと、その下で自分の割り当てを持たないスロットはすべて無効になります。
• ルートまで割り当てがなければ、その機能は未設定です。呼び出しはスロット名を示すエラーで失敗し、どのベンダーにもフォールバックしません。
• 要件（requirement）はそれを宣言したスロットに属し、割り当てか継承かにかかわらず、そのスロットが解決したモデルに対してチェックされます。agent はツール呼び出しを必要とし、組み込みカタログがそのモデルは非対応だとしている場合、エージェントは妥協せずに実行を拒否します。カタログにないモデルは許可されます。agent.title には要件がないので、小さいモデルを使えます。

割り当て Copy Section

割り当ての書き方は 4 通りです。

slots:
  llm: openai:gpt-5.5            # プロバイダー:モデル
  webSearch: tavily              # プロバイダーのみ：その既定モデル
  course.outline:                # パラメーター付きのオブジェクト
    model: openai:gpt-5.5
    fallback: anthropic:claude-sonnet-4-6
    thinking: { effort: low }
  video: null                    # 無効

オブジェクト形式で使えるフィールド：

agent スロットでは thinking.effort を設定できません。ツール呼び出しの転送方式では推論強度と関数ツールを併用できないためです。

プロバイダーのみの参照 Copy Section

:model のない参照は、そのプロバイダーの既定モデルを意味します。Token Plan がその機能に推奨するモデル、なければ組み込みレジストリの既定モデルです。検索やドキュメントのサービスはほとんど選べるモデルがないため、webSearch: tavily や document: mineru-cloud と書くのが普通です。チャットスロットには必ずモデルを書き、llm: openai は起動時に拒否されます。

フォールバック Copy Section

フォールバックは言語モデルのスロット、つまり llm とその下のすべてのスロットにだけ適用されます。tts、asr、image、video、webSearch、webFetch、document のスロットに書いた fallback は拒否されます（openmaic.yml では起動時、モデル設定では保存時）。

主モデルの呼び出しが自身の再試行の後も再試行可能な失敗で終わった場合、スロットの fallback で一度だけ再試行します。再試行可能な失敗とは、SDK が一時的と判断したエラー、タイムアウト、ネットワークエラー、レート制限（429）、容量不足（503）、または空の出力です。プロバイダーがクォータ切れを明示的に返した場合（insufficient_quota などの OpenAI 互換のクォータコード。HTTP ステータスは問いません）は、主モデルで再試行せず、すぐにフォールバックに切り替えます。コンテンツ安全性による拒否やその他の 4xx エラーではフォールバックしません。フォールバックは通常の呼び出しとストリーミング呼び出しの両方に適用され、スロットの thinking パラメーターを使います。

フォールバックは割り当ての一部であり、割り当てと一緒に継承されます。自分の割り当てを持たない course.content.slide は、course.content のモデルとフォールバックを使います。要件のあるスロットは、要件を満たさないフォールバックでは再試行しません。

機能を無効にする Copy Section

そのスロットに null を書きます。video: null は既定で動画生成を無効にしますが、ユーザーはモデル設定で有効にできます。全員に対して無効のままにするには lock: [video] を加えます。course.content.pbl: null は PBL シーンの生成だけを無効にし、course.content の残りは通常どおり動きます。無効なスロットへの呼び出しは即座に失敗し、メディア系の API は別のベンダーを選ぶ代わりに 403 を返します。

既定値・ロックとモデル設定 Copy Section

openmaic.yml が slots に書いたものはサーバーの既定値です。ユーザーはモデル設定で変更でき、カードには サーバー既定 と表示され、サーバー既定に戻す で変更を取り消せます。lock に挙げたものは管理者が固定し、サブツリー全体とともに全員に対して固定されます。

lock: [llm, video]   # これらのスロットとその下のすべてのスロット
# lock: all          # すべてのスロット

• lock に挙げるスロットはすべて slots に書かれている必要があります（null も含みます。video: null と lock: [video] で全員の動画が無効のままになります）。未知のスロットや、slots に書かれていないロック対象のスロットがあると、位置（lock.1: ...）を示してサーバーは起動しません。
• ロックしたスロットは子も固定します。lock: [llm] では、どのユーザーも course.outline などの言語モデルスロットを設定できず、すべて openmaic.yml だけで解決されます。
• lock: all は書かれているかどうかにかかわらずすべてのスロットを固定します。slots に書かれていない機能のルートは、全員に対して未設定になります。ただし未指定の webFetch は builtin を使用し、webFetch: null で無効にできます。
• null、サーバーの既定値、ロックは組み合わせて使えます。video: null だけなら既定で無効でユーザーが有効にでき、lock: [video] を加えると無効のままです。

設定画面は、構成に応じて次の三つの形のいずれかになります。

すべてのコントロールは同じ規則に従います。使って何かが変わる場合にだけ表示されます。モデルサービスの各機能のタブとサービスの追加は、その機能にユーザーが設定できるスロットが残っている間だけ表示されます。Token Plan は、プランがまだロックされていないスロットを埋められる間だけ表示され、プランを接続してもロックされたスロットには触れません。コースモデル設定でロックされたカードは、管理者が固定 と表示された読み取り専用の 1 行になります。ホームページのモデル選択は、既定モデルを変更できる場合（llm がロックされておらず、言語モデルを提供するプロバイダーがある場合）にだけ表示されます。

Web アプリのモデル設定は、現在のワークスペースについて同じ木を読み書きします。

• Token Plan：プランを接続すると、そのキーでプランのプロバイダーを追加し、プランが推奨するスロットのうちまだ割り当てのないものにモデルを設定します。接続を解除するとプロバイダーが削除され、それを使っていたスロットは親に従います。
• モデルサービス：機能ごとのタブ（言語モデル、画像、動画、音声合成、音声認識、ドキュメント解析、Web 検索）にそれぞれのサービスが並びます。openmaic.yml のプロバイダーは読み取り専用で表示され、キーに関する情報は一切表示されません。ワークスペースが設定したサービスはワークスペースのプロバイダーになり、キーは書き込み専用で …abcd のようなマスクだけが表示されます。独自のエンドポイントは言語モデルのみ（Azure Speech はリージョンの公式エンドポイント、例えば https://<region>.tts.speech.microsoft.com を使います）、セルフホストのサービスとキーペアは openmaic.yml で設定します。テストボタンは保存済みのプロバイダーをサーバー側で確認します。
• コースモデル設定：メインモデルは llm スロット、パイプラインの各工程はそれぞれのスロットです（メインモデルに従う＝その工程に独自の割り当てがない）。画像・動画・音声・検索・文字起こしのスイッチはスロットを null にします。ロックされたスロットは読み取り専用の 1 行になり、サーバー既定のスロットはユーザーが変更すると サーバー既定に戻す を表示します。

以前のバージョンでブラウザーに保存されていたプロバイダー設定（プロバイダーとそのキーや Base URL、選択したモデル、Token Plan の接続状態、各機能の選択）は、ワークスペースに一度だけインポートされます。インポートはワークスペースの既存の設定や openmaic.yml がロックしたサブツリーのスロットを置き換えず、allowUserKeys: false や検証で拒否された項目はスキップします。2xx の応答を受けた後、ブラウザーから削除されるのはワークスペースが保持した項目だけです。サーバーがスキップした項目（メディアサービスの独自エンドポイント、ワークスペースで使えないプリセット、デプロイが宣言しているプロバイダー ID など）はキーとともにこのブラウザーに残り、再送されることはなく、設定し直すか破棄するまで「設定 → モデルサービス」に理由とともに表示されます（通知は一度だけです）。リージョンの公式エンドポイントを持つ Azure Speech のプロバイダーはインポートされます。400 の場合はインポート内容全体が拒否され、再送はされず、各項目はキーとともにこのブラウザーに残り、スキップされた項目と同様に表示されます。インポート内容が読み取れない場合は破棄されます。401、404、409、5xx、ネットワークエラーの場合だけ、後で再試行するためにブラウザーに残ります。明示的にオフにしていた音声入力は asr: null になり、使えるプロバイダーがある状態でオフにしていたナレーション・画像・動画は tts: null・image: null・video: null になります（openmaic.yml がロックしたスロットはそのままです）。次のものは手動で設定し直す必要があります：ステージ別のモデル（コースモデル設定、または openmaic.yml の slots）、推論設定（スロットの thinking）、独自の音声合成・文字起こしプロバイダーと AliDocMind のキーペア（openmaic.yml。これらはブラウザーに残り、スキップされた項目と一緒に表示されます）、VoxCPM のバックエンド（options.backend）、Baidu 検索のサブソース（サーバーの既定値が適用されます）。オフにしていた調査のスイッチは引き継がれません（コースの調査を止めるだけで、チャットとエージェントは検索を続けていました）。既定値のためにオフだっただけのスイッチも引き継がれません。各機能はスロットが解決される限り動作します。

ワークスペースとは永続化のドキュメントでいうオーナー（owner）です。既定の Docker Compose 構成（シングルユーザーモード）ではワークスペースは 1 つで、マルチユーザー構成ではサインインした各アカウントが自分のワークスペースを持ちます。

allowUserKeys Copy Section

allowUserKeys: false

allowUserKeys（既定値 true）は、ユーザーが独自のプロバイダー、キー、Token Plan を追加できるかどうかを決めます。false の場合、ユーザーは openmaic.yml が宣言したプロバイダーの中から、ロックされていないスロットについてのみ選択できます。Token Plan とサービスの追加は表示されず、ワークスペースが以前に追加したプロバイダーも使われなくなります。リクエストが独自のモデル、キー、エンドポイントを指定しても（非推奨の x-model、x-api-key、x-base-url ヘッダーや、メディア系 API のプロバイダーフィールド）無視され、プロバイダーのテストボタンのヘッダー形式は拒否されます。すべての利用料を負担するマルチユーザー環境では、通常これを設定し、固定したいスロットをロックします。

シークレットと OPENMAIC_SECRET_KEY Copy Section

• openmaic.yml のキーは ${VAR} で環境変数から読み込まれ、データベースに保存されることもブラウザーに送られることもありません。
• ワークスペースがモデル設定で入力したキーはデータベースに保存され、インスタンスシークレット OPENMAIC_SECRET_KEY を使って AES-256-GCM で暗号化されます。
• OPENMAIC_SECRET_KEY が未設定の場合、サーバーは初回使用時に data/instance-secret.key（Docker Compose では openmaic-data ボリューム内）にランダムなシークレットを作成し、以降それを使います。

シークレットはデータベースのバックアップと一緒に保管してください。失われたり変更されたりしたシークレットで保存されたキーは読み取れず、再入力が必要です（モデル設定に表示されます）。複数のインスタンスが同じデータベースを共有する場合や、サーバーに永続的なデータディレクトリがない場合（データボリュームをマウントしていないコンテナなど）は、OPENMAIC_SECRET_KEY を明示的に設定してください。任意の文字列を使えます（例：openssl rand -base64 32 の出力）。

設定しない場合、再起動をまたいで残らないデータディレクトリ（ボリュームのないコンテナや一時ディスク）では起動のたびに新しいシークレットが作られ、複数のレプリカはそれぞれ別のシークレットを作ります。作業ディレクトリが読み取り専用ならシークレットを作成できず、モデル設定でのキー保存は失敗します。起動時、OPENMAIC_SECRET_KEY が未設定でデータディレクトリに書き込めない場合や、データベースに現在とは別のシークレットで封印されたキーがある場合（data/instance-secret.key を失った場合など）、サーバーは警告を記録しますが、起動は続けます。

OPENMAIC_SECRET_KEY=...        # モデル設定に保存されるキー用のインスタンスシークレット
OPENMAIC_CONFIG=/etc/openmaic/openmaic.yml   # 任意：openmaic.yml の別のパス

ワークスペースが追加できるもの Copy Section

openmaic.yml のプロバイダーはスキーマが許すものなら何でも構いません。ワークスペースがモデル設定で追加するプロバイダーは、エンドポイントとキーを Web アプリのユーザーが入力するため、より制限されます。

• Amazon Bedrock は提供されません。サーバー自身の AWS 認証情報で署名してしまうためです。
• proxy とキーペア（credentials）は使えません。AliDocMind などキーペアで認証するプリセットはデプロイ専用です。
• 独自の baseUrl はチャットを提供するプリセットでのみ使え、それを持つプロバイダーはチャットスロット専用になります。URL には認証情報、クエリ文字列、フラグメントを含められず、サーバーが ALLOW_LOCAL_NETWORKS=true を設定していない限り公開アドレスに解決される必要があります。このエンドポイントへのリクエストはリダイレクトに従いません。
• ローカルのモデルサーバー（Ollama、Lemonade）は、プリセット既定の localhost ではなく自分のエンドポイントを指定する必要があります。
• セルフホストのメディア・検索・ドキュメントサービス（VoxCPM2、FunASR、Lemonade の音声と画像、ComfyUI、SearXNG、セルフホストの MinerU）はサーバー自身のネットワーク上で動くため、デプロイ専用です。
• 運用者が旧来の <CAP>_<VENDOR>_ENABLED=false 変数で無効にしたプロバイダーは提供されません。
• ワークスペースは openmaic.yml が既に宣言しているプロバイダー ID を宣言できません。

ユーザーに内部サービスを使わせたい場合は、そのプロバイダーを openmaic.yml で宣言してください。

API クライアントと非推奨のリクエストフィールド Copy Section

生成リクエストでキーやモデルの選択を送る必要はなくなりました。/api/generate-classroom のようなブラウザーを使わない API 呼び出しも、呼び出し元のワークスペースについて Web アプリと同じスロットで解決されます。

旧来のリクエストヘッダー x-model、x-api-key、x-base-url、x-provider-type、x-model-routes、x-image-provider、x-image-model、x-video-provider、x-video-model、および音声・検索・ドキュメント API の対応するボディフィールドは非推奨です。これらは、影響するスロットに何も割り当てられていない間、またはレガシー変数で構成されたままのサーバーで、それらから変換された既定値しかない間だけ有効です（DEFAULT_MODEL は以前からリクエストが指定したモデルより優先度が低いため）。openmaic.yml の既定値、ワークスペース自身の選択、ロックされたスロットが優先され、null のスロットはリクエストの内容にかかわらず拒否されます。allowUserKeys: false の場合は常に無視されます。リクエストが初めてこれらを使ったとき、サーバーは警告をログに記録します。上記のモデル設定のリリースから 2 マイナーバージョン後に削除される予定です。

旧設定からの移行 Copy Section

openmaic.yml がない場合、サーバーは起動時に旧設定を変換し、非推奨の通知と、変換できなかった項目ごとの通知をログに出します。

openmaic.yml がある場合、プロバイダー変数、server-providers.yml、DEFAULT_MODEL、MODEL_FALLBACK、MODEL_ROUTES はモデルの解決に使われず、その旨が通知されます。<CAP>_<VENDOR>_ENABLED=false は引き続き適用されます。機能を無効にするには、代わりにスロットを null にしてください。

環境変数。 移行前：

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEFAULT_MODEL=openai:gpt-5.5
MODEL_FALLBACK=anthropic:claude-sonnet-4-6
TTS_MINIMAX_API_KEY=...
TAVILY_API_KEY=tvly-...

移行後（キーは環境変数に残します）：

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}
  anthropic:
    preset: anthropic
    apiKey: ${ANTHROPIC_API_KEY}
  minimax-tts:
    preset: minimax-tts
    apiKey: ${TTS_MINIMAX_API_KEY}
  tavily:
    preset: tavily
    apiKey: ${TAVILY_API_KEY}

slots:
  llm:
    model: openai:gpt-5.5
    fallback: anthropic:claude-sonnet-4-6
  tts: minimax-tts
  webSearch: tavily

その後 DEFAULT_MODEL と MODEL_FALLBACK を削除します。プロバイダー変数は ${VAR} 参照の元として残して構いません。_BASE_URL はプロバイダーの baseUrl になり（OPENAI_BASE_URL → openai の baseUrl。URL を直接書くか、変数を設定したままなら ${OPENAI_BASE_URL} と書きます）、_MODELS はその models リストになります。変換された DEFAULT_MODEL と同じく、ここに書いた llm はワークスペースが変更できるサーバーの既定値です。全員に対して固定するには lock: [llm] を加えてください。変換結果と異なり、agent は llm に従うようになります。Pro エージェントを無効のままにするには agent: null と書いてください。

server-providers.yml。 移行前：

providers:
  azure:
    apiKey: ...
    baseUrl: https://YOUR-RESOURCE.openai.azure.com/openai
    models: [my-deployment]
pdf:
  alidocmind:
    accessKeyId: ...
    accessKeySecret: ...
web-search:
  searxng:
    baseUrl: http://searxng:8080

移行後：

providers:
  azure:
    preset: azure
    apiKey: ${AZURE_OPENAI_API_KEY}
    baseUrl: https://YOUR-RESOURCE.openai.azure.com/openai
    models: [my-deployment]
  alidocmind:
    preset: alidocmind
    credentials:
      accessKeyId: ${ALIDOCMIND_ACCESS_KEY_ID}
      accessKeySecret: ${ALIDOCMIND_ACCESS_KEY_SECRET}
  searxng:
    preset: searxng
    baseUrl: http://searxng:8080

slots:
  llm: azure:my-deployment
  document: alidocmind
  webSearch: searxng

server-providers.yml の各セクションは、対応するプリセットのプロバイダーになります（providers → チャットのプリセット、tts、asr、pdf → ドキュメント、image、video、web-search）。accessKeyId／accessKeySecret は credentials の下に移します。

MODEL_ROUTES。 openmaic.yml なしで MODEL_ROUTES を設定したサーバーは起動しません。

MODEL_ROUTES does not carry over to the model configuration: write the per-stage models as slots in openmaic.yml (or the file named by OPENMAIC_CONFIG) and remove MODEL_ROUTES

ステージ別のルートはスロットと 1 対 1 に対応しないため、変換されません。各ルートを、そのステージが属するスロットとして書き直してください。

複数のステージが 1 つのスロットを共有する場合は、それらが使うべき 1 つのモデルをスロットに指定します。ルートの thinking はスロットの thinking に、maic-agent-driver ルートの api と contextWindow は agent スロットに移します。移行前：

DEFAULT_MODEL=openai:gpt-5.5
MODEL_ROUTES='{"scene-outlines-stream":"anthropic:claude-sonnet-4-6","scene-content:slide":{"model":"openai:gpt-5.4","thinking":{"effort":"low"}},"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

移行後：

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}
  anthropic:
    preset: anthropic
    apiKey: ${ANTHROPIC_API_KEY}

slots:
  llm: openai:gpt-5.5
  course.outline: anthropic:claude-sonnet-4-6
  course.content.slide:
    model: openai:gpt-5.4
    thinking: { effort: low }
  agent:
    model: openai:gpt-5.5
    api: openai-completions

openmaic.yml が存在すると、プロバイダー変数だけでは何も設定されません。変数だけで設定していた TTS、画像、ドキュメント、Web 検索のプロバイダー（TTS_MINIMAX_API_KEY、IMAGE_SEEDREAM_API_KEY、PDF_MINERU_BASE_URL、TAVILY_API_KEY など）は使われなくなり、webFetch 以外の機能にはデフォルトのプロバイダーは割り当てられません。使用するプロバイダーをすべて providers に宣言し、上の環境変数の例と同様に slots で tts、image、document、webSearch（および asr、video）を割り当ててください。割り当てられていないその他のスロットは、ワークスペースがモデル設定で割り当てない限り未設定のままです。

その後 MODEL_ROUTES、DEFAULT_MODEL、MODEL_FALLBACK を削除します。

Docker。 ファイルをアプリの隣にマウントし、キーは .env.local に置きます。

services:
  openmaic:
    volumes:
      - ./openmaic.yml:/app/openmaic.yml:ro

ACCESS_CODE — サイト全体のパスワード Copy Chapter

共有デプロイ（社内デモ、授業など）ではアクセスコードを設定し、訪問者にアプリ表示前のパスワード入力を求められます。

ACCESS_CODE=your-secret-code

十分な長さのランダムな値（16 文字以上）を使用してください。このコードはデプロイを保護する唯一の秘密です。検証に成功すると、署名付きトークンが HTTP-only cookie に 7 日間保存され、有効期限はサーバー側で検証されるため、期限切れ後は再入力が必要です。検証レートの制限は、x-forwarded-for / x-real-ip を上書きする信頼できるリバースプロキシの背後で TRUST_PROXY_HEADERS=true を設定した場合にのみ有効になり、クライアント単位で 60 秒あたり 10 回に制限されます。検証に成功するとそのクライアントのカウントは消去されます。信頼できるプロキシがない場合、リクエストをクライアントに紐付けられないため制限は行われず、コードの長さとランダム性が防御になります。空欄にすると無効になります。

機能フラグ Copy Chapter

機能フラグは true または 1 を有効とし、特記がない限りそれ以外は無効です。NEXT_PUBLIC_* はビルド時にクライアントに注入されるため、変更後は再ビルドが必要です。

# MAIC Editor（Pro モード）
NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true

# Pi 再生時の PPT・インタラクティブ教材参照（ビルド時フラグ。編集モードの参照には影響しません）
NEXT_PUBLIC_COURSEWARE_REFERENCE_ENABLED=true

# 職業教育タスクエンジン（サーバー側スイッチ）
OPENMAIC_ENABLE_VOCATIONAL=true

# 職業教育実験 UI 表示
NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI=true

# 動画エクスポート入口表示
NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true

# 実験的 PPTX インポート入口表示
NEXT_PUBLIC_ENABLE_PPTX_IMPORT=true

教室チャットは常に Pi で動作し、ツール／関数呼び出しに対応したモデルが必要です。コースモデル設定の教室で対応モデルを選択するか、openmaic.yml の classroom スロット（または継承元の llm スロット）を設定してください。Gemini では Google の OpenAI 互換エンドポイントではなく、ネイティブの google プリセットを使います。 組み込みカタログでツール呼び出し非対応とされているモデルは推論前に 400 MODEL_CONFIG_INVALID（reason: tool_calling_required）で拒否され、コースモデル設定でも教室スロットにこの要件が表示されます。

従来の director-graph 教室チャットは削除され、NEXT_PUBLIC_PI_CHAT_ENABLED で対話経路を選ぶことはできなくなりました。この変数は設定から削除してください。production ビルドが受け付けるのは未設定、空文字列、true、1（完全一致）のみで、それ以外の値では移行案内とともにビルドが失敗します。Docker Compose では、サービスの env_file（.env.local）が渡すのは実行時の値であり、ビルド引数には入りません。

PPTX インポートはまだ実験的で、解析結果は完全に授業データフローに統合されていません。NEXT_PUBLIC_* 変数はビルド時スイッチで、Docker では build args で渡す必要があり、コンテナ実行時環境変数だけでは反映されません。

その他サーバーオプション Copy Chapter

以下のサーバーオプションも環境変数で設定可能です：

# シーン内容の並列生成。0 または未設定は逐次生成
PARALLEL_SCENE_CONCURRENCY=3

# localhost や内部ネットワークへのアクセス許可。セルフホスト／プライベートネットワーク向け
ALLOW_LOCAL_NETWORKS=true

# 任意の MP4 レンダリングサービス
RENDER_SERVICE_URL=http://render-service:9000

# ログと推論設定
LOG_LEVEL=info
LOG_FORMAT=pretty
LLM_THINKING_DISABLED=false

旧来のプロバイダー環境変数 Copy Chapter

これらの変数と server-providers.yml は以前のリリースの設定方法です。openmaic.yml がない場合は引き続き動作しますが（旧設定からの移行を参照）、非推奨であり、モデル設定のリリースから 2 マイナーバージョン後に削除されます。openmaic.yml を使う場合は ${VAR} 参照の元としてのみ使ってください。DEFAULT_MODEL と MODEL_FALLBACK は移行のセクションで説明しています。MODEL_ROUTES はもう読み込まれません。

LLM プロバイダー Copy Section

クラウドプロバイダーは通常、API key、base URL、モデル一覧の3つの環境変数を使います。API key は必須の場合が多く、base URL とモデル一覧は任意です。Azure OpenAI はリソース endpoint の設定が必要で、Ollama と Lemonade は API key 不要です。

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=                # 任意の base URL 上書き
OPENAI_MODELS=                  # 任意の許可モデル一覧（カンマ区切り）

対応している provider prefix:

Azure OpenAI は deployment name をモデル ID として使います：

AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_BASE_URL=https://YOUR-RESOURCE.openai.azure.com/openai
AZURE_OPENAI_MODELS=your-deployment-name

別の OpenAI 互換 LLM サービスに接続するには、openmaic.yml で baseUrl と models を指定した openai-compatible プロバイダーを宣言するか、設定 → モデルサービス → 言語モデル の プロバイダーを追加 で追加してください。

Gemini の教室チャットにはネイティブの google プリセットを使います。設定 → モデルサービスで Google を追加し、コースモデル設定の教室で選択してください。Pi は Google 公式の OpenAI 互換エンドポイント（https://generativelanguage.googleapis.com/v1beta/openai）を早期に拒否し、移行を案内します。互換経路のツール呼び出し対応は #1556 で追跡しています。このチェックは公式エンドポイントのみを識別し、任意のサードパーティゲートウェイの接続先は識別できません。

ローカルモデル（Ollama と Lemonade） Copy Section

Ollama と Lemonade は API key 不要です。ローカルサービスの base URL はサーバー側設定に書き、SSRF チェックを通過させます。

OLLAMA_BASE_URL=http://localhost:11434/v1
# LEMONADE_BASE_URL=http://localhost:13305/v1

利用可能モデルを制限したい場合は、OLLAMA_MODELS または LEMONADE_MODELS でホワイトリストを指定できます。

TTS プロバイダー Copy Section

サーバー側 TTS プロバイダーは TTS__API_KEY と任意の TTS__BASE_URL を使います。

# Doubao TTS（Volcengine Seed-TTS、ネイティブ MP3）
TTS_DOUBAO_API_KEY=appId:accessKey
TTS_DOUBAO_BASE_URL=       # 任意の上書き

# Qwen TTS
TTS_QWEN_API_KEY=
TTS_QWEN_BASE_URL=         # 任意の上書き

# 任意の OpenAI 互換 TTS エンドポイント
TTS_OPENAI_API_KEY=
TTS_OPENAI_BASE_URL=

# VoxCPM2（セルフホスト TTS、音声クローン対応。VoxCPM2 ページを参照）
TTS_VOXCPM_BASE_URL=http://localhost:8000

対応している TTS prefix は TTS_OPENAI_、TTS_AZURE_、TTS_GLM_、TTS_QWEN_、TTS_MINIMAX_、TTS_DOUBAO_、TTS_ELEVENLABS_、TTS_GOOGLE_、TTS_VOXCPM_、TTS_LEMONADE_ です。ローカル Lemonade TTS と VoxCPM2 は API key 不要です。ブラウザのネイティブ TTS はサーバー設定不要です。

管理者は TTS__ENABLED=false で特定の TTS プロバイダーをサーバー側で強制無効化できます。VoxCPM2（セルフホスト TTS＋音声クローン）については専用の VoxCPM2 ページを参照してください。

別の OpenAI 互換 TTS エンドポイントを使うには、openmaic.yml でその baseUrl を指定した openai-tts プロバイダーを宣言し、tts スロットに割り当ててください。ワークスペースはモデル設定で独自の TTS エンドポイントを追加できません。

ASR（音声認識） Copy Section

# OpenAI Whisper
ASR_OPENAI_API_KEY=
ASR_OPENAI_BASE_URL=       # 任意の上書き

# Qwen ASR
ASR_QWEN_API_KEY=
ASR_QWEN_BASE_URL=         # 任意の上書き

# Azure ASR
ASR_AZURE_API_KEY=
ASR_AZURE_BASE_URL=https://{region}.api.cognitive.microsoft.com

# FunASR（ローカル、key 不要）
ASR_FUNASR_BASE_URL=http://localhost:8000/v1

# Lemonade ASR（ローカル、key 不要）
ASR_LEMONADE_BASE_URL=http://localhost:13305/v1

funasr-server --device cuda で OpenAI 互換サービスを起動します。/v1/audio/transcriptions で WAV を受け付け、モデル選択から SenseVoiceSmall、Paraformer、Fun-ASR-Nano を利用できます。

ブラウザのネイティブ ASR はサーバー設定不要です。

別の OpenAI 互換 ASR エンドポイントを使うには、openmaic.yml で openai-whisper プリセットとその baseUrl を指定して宣言し、asr スロットに割り当ててください。ワークスペースはモデル設定で独自の ASR エンドポイントを追加できません。

providers:
  my-asr:
    preset: openai-whisper
    apiKey: ${MY_ASR_API_KEY}
    baseUrl: https://asr.example.com/v1

slots:
  asr: my-asr:whisper-1

画像生成プロバイダー Copy Section

画像生成プロバイダーは IMAGE__API_KEY と任意の IMAGE__BASE_URL を使います。対応 prefix は以下の通りです：

IMAGE_OPENAI_、IMAGE_SEEDREAM_、IMAGE_QWEN_IMAGE_、IMAGE_NANO_BANANA_、IMAGE_MINIMAX_、IMAGE_GROK_、IMAGE_GLM_、IMAGE_LEMONADE_

GLM Image（Zhipu CogView）は CogView モデル（cogview-3-flash、cogview-4）で画像を生成します：

providers:
  glm-image-service:
    preset: glm-image
    apiKey: ${IMAGE_GLM_API_KEY}
    # 任意:
    baseUrl: https://open.bigmodel.cn/api/paas/v4

slots:
  image: glm-image-service:cogview-3-flash

環境変数でも設定できます：

IMAGE_GLM_API_KEY=
# 任意:
IMAGE_GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4

Lemonade はローカルサービスで API key 不要です：

IMAGE_LEMONADE_BASE_URL=http://localhost:13305/v1

ComfyUI Image に API キーは不要です。自分のネットワーク上で動くため、デプロイ側で設定します。openmaic.yml で ComfyUI サーバーのアドレスを指定して宣言し、image スロットに割り当ててください。

providers:
  comfyui:
    preset: comfyui-image
    baseUrl: http://host.docker.internal:8188

slots:
  image: comfyui

API 形式でエクスポートしたワークフロー JSON を OpenMAIC の public/ ディレクトリに置きます。ファイル名は comfyui-*.json に一致するか workflow を含む必要があり、OpenMAIC はこれらを自動的に検出してワークフローとして提供します。Docker では、イメージをビルドする前にワークフローを追加するか、個々のワークフローファイルをコンテナ内の /app/public/ にマウントしてください。プロバイダーはデプロイで宣言されているため、ホストやプライベートネットワーク上の ComfyUI に ALLOW_LOCAL_NETWORKS は不要です。

動画生成プロバイダー Copy Section

動画生成プロバイダーは VIDEO__API_KEY と任意の VIDEO__BASE_URL を使います。対応 prefix は：

VIDEO_SEEDANCE_、VIDEO_KLING_、VIDEO_SORA_、VIDEO_MINIMAX_、VIDEO_GROK_、VIDEO_HAPPYHORSE_

ドキュメント・メディア解析 Copy Section

教材の具体的なフォーマットは選択したパーサーに依存します。現在はテキスト、PDF、Office 文書、画像、一部の音声・動画形式をサポートし、provider によって対応範囲が異なります。

# MinerU 自ホスト
PDF_MINERU_BASE_URL=http://localhost:8888

# MinerU 自ホストのオプションバックエンド
PDF_MINERU_BACKEND=pipeline

# MinerU Cloud
PDF_MINERU_CLOUD_API_KEY=
PDF_MINERU_CLOUD_BASE_URL=https://mineru.net/api/v4

# AliDocMind（API key ではなく Alibaba Cloud AccessKey を使用）
ALIDOCMIND_ACCESS_KEY_ID=
ALIDOCMIND_ACCESS_KEY_SECRET=
ALIDOCMIND_BASE_URL=       # 任意の上書き

unpdf は OpenMAIC に組み込み済みで、基本的な PDF 解析に使えます。Office 文書、画像、OCR、表、数式、レイアウト解析が必要な教材は MinerU または AliDocMind の互換 provider を選択してください。

AliDocMind のドキュメント解析は PDF、DOCX、PPTX、XLSX、PNG、JPG/JPEG、BMP、GIF に対応します。現在の音声・動画素材は AliDocMind でのみ解析可能で、動画は MP4、MOV、AVI、MKV、WMV、音声は MP3、WAV、AAC に対応し、M4A は非対応です。

Web 検索 Copy Section

Tavily、Exa、Firecrawl、Bocha、Brave、Baidu、SearXNG、MiniMax を設定可能です。

TAVILY_API_KEY=
TAVILY_BASE_URL=           # 任意の上書き

EXA_API_KEY=
EXA_BASE_URL=https://api.exa.ai  # 任意の上書き

FIRECRAWL_API_KEY=
FIRECRAWL_BASE_URL=https://api.firecrawl.dev  # 任意の上書き

BOCHA_API_KEY=
BOCHA_BASE_URL=            # 任意の上書き

BAIDU_API_KEY=
BAIDU_BASE_URL=https://qianfan.baidubce.com  # 任意の上書き

# 自ホスト SearXNG（API key 不要）
SEARXNG_BASE_URL=

WEB_SEARCH_MINIMAX_API_KEY=
WEB_SEARCH_MINIMAX_BASE_URL=https://api.minimaxi.com  # 任意の上書き

Brave と SearXNG は API key 不要です。Web 検索には生成ごとのスイッチはなく、ワークスペースの webSearch スロットが解決される限り実行されます。無効にする（openmaic.yml で webSearch: null、または 設定 → コースモデル設定 の検索スイッチで無効化）と、そのワークスペースの以降の生成に影響します。Grok の Web 検索は Grok LLM の検索ツール経由で提供され、独立した Web 検索 provider ではありません。

server-providers.yml Copy Section

openmaic.yml に置き換えられ、非推奨です。両方がある場合、モデルの設定には openmaic.yml だけが使われます。

環境変数のほかに、コード内で登録済みの provider 設定をプロジェクトルートの server-providers.yml に書くこともできます。サーバー起動時に読み込まれ、環境変数のカテゴリに対応した構造です。

providers:
  openai:
    apiKey: sk-...
    baseUrl: https://api.openai.com/v1
    models:
      - gpt-5.5
  anthropic:
    apiKey: sk-ant-...

tts:
  doubao-tts:
    apiKey: appId:accessKey

asr:
  openai-whisper:
    apiKey: sk-...

pdf:
  mineru:
    baseUrl: http://localhost:8888
  alidocmind:
    accessKeyId: your-access-key-id
    accessKeySecret: your-access-key-secret

image:
  seedream:
    apiKey: ...

video:
  seedance:
    apiKey: ...

web-search:
  tavily:
    apiKey: tvly-...
  exa:
    apiKey: ...
  firecrawl:
    apiKey: fc-...
  searxng:
    baseUrl: http://localhost:8080

環境変数は YAML の同名フィールドを逐次上書きします。キーはコード内登録済みの provider ID（例：openai、doubao-tts、openai-whisper、mineru、alidocmind、seedream、seedance、exa、tavily、searxng）でなければなりません。未知の ID でカスタム LLM provider を登録することはできません。

サーバー管理プロバイダーのモデル認可 Copy Chapter

デプロイの認証情報を使って選択されたモデルを上流へ送るプロバイダーには、openmaic.yml で明示的な models リスト（providers..models）を設定するか、対応する *_MODELS 環境変数 / server-providers.yml の該当セクションの models リストを設定してください。対象はチャット、画像、動画、音声合成、音声認識、モデルベースの Web 検索です。モデル ID は設定読み込み時に前後の空白を除いたうえで、大文字小文字も含め完全一致で照合されます。決定的なアダプターエイリアスは、宣言されたモデル ID で認可されます。リストにないモデルへのリクエストは HTTP 403、PROVIDER_DISABLED、メッセージ「This model is not authorized for server-managed credentials」を返します。

破壊的変更： 明示的なリストがない場合に使えるのは、デプロイの既定/フォールバックモデルと、その機能のスロットが参照するプライマリ/フォールバックモデルだけです。旧設定では DEFAULT_MODEL と MODEL_FALLBACK がチャットモデルを認可します。プロバイダーのみを指定したメディアスロットは、そのアダプターの既定モデル 1 つだけを認可し、プリセットのカタログ全体は認可しません。ワークスペースの割り当てでデプロイの認可範囲を広げることはできません。音声登録と合成でも、音声互換性のために選ばれたモデルを認可する必要があります。

移行するには、ユーザーが選べるべきモデルをすべて列挙し、サーバーを再起動し、認可されなくなったワークスペースの選択を更新してください。認証情報があってリストのないプロバイダーについては、追加すべき設定が起動ログに表示されます。ユーザー自身のプロバイダー認証情報と、Ollama や Lemonade のような key 不要のローカルプロバイダーは影響を受けません。認証情報なしで設定されたプロバイダーは制限されないため、独自に上流の認証情報を付加するゲートウェイ（社内の OpenAI 互換プロキシなど）に向けないでください。そのゲートウェイに key を与えて models リスト付きの認証情報ありプロバイダーとして設定するか、ゲートウェイ側でモデルを制限してください。モデル選択のないドキュメントパーサーや検索サービス（Tavily など）にはモデルリストは不要です。

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}
    models: [gpt-5.4-mini]
slots:
  llm: openai:gpt-5.4-mini

旧設定での同等の書き方：OPENAI_API_KEY=... と OPENAI_MODELS=gpt-5.4-mini。メディアでは機能プレフィックスを使います。例：IMAGE_SEEDREAM_MODELS、VIDEO_SEEDANCE_MODELS、TTS_OPENAI_MODELS、ASR_OPENAI_MODELS、WEB_SEARCH_CLAUDE_MODELS。

DeepSeek の Web 検索と取得 Copy Section

deepseek プリセットはチャット、Web 検索、ホスト型 Markdown 抽出で DEEPSEEK_API_KEY と API ベース URL を共有します。検索は POST /v1/tools/search を使い、最大 50 件を返します。クエリは Unicode コードポイント単位で 128 文字に切り詰め、結果には summary、空の場合は snippet を使います。取得は POST /v1/tools/fetch を使い、content と空でない任意の title を読み取ります。

旧設定では WEB_SEARCH_DEEPSEEK_ENABLED=true、または server-providers.yml の明示的な web-search.deepseek エントリーで有効にします。チャットの認証情報だけでは検索を有効にせず、既存の検索の既定値も変更しません。WEB_SEARCH_DEEPSEEK_ENABLED=false は検索を強制無効化します。openmaic.yml がある場合、旧変数はスロットを割り当てられません。プロバイダーを宣言し、webSearch と／または webFetch を明示的に割り当ててください。

The default API base is https://api.deepseek.com/v1. On api.deepseek.com, every base path (including /beta) is normalized to /v1 before appending /tools/search or /tools/fetch. Custom gateway bases preserve their configured path prefix; a bare root gets /v1 first. Custom endpoints belong in deployment configuration, while client and workspace overrides remain restricted to official endpoints. The default fetch reader remains builtin. See DeepSeek official pricing for current request charges. Failed requests and searches with no results are not billed.

providers:
  deepseek:
    preset: deepseek
    apiKey: ${DEEPSEEK_API_KEY}
    baseUrl: https://api.deepseek.com/v1
slots:
  webSearch: deepseek
  webFetch: deepseek

Kimi のチャットと Web 検索 Copy Section

Kimi アカウントを 1 つ宣言し、両方のスロットを割り当てます：

providers:
  kimi:
    preset: kimi
    apiKey: ${KIMI_API_KEY}
    # 任意：国際版 Open Platform では https://api.moonshot.ai/v1 を使用します。
    # baseUrl: https://api.moonshot.ai/v1
slots:
  llm: kimi:kimi-k3
  webSearch: kimi

Coding Plan のキーには preset: kimi-coding-plan と llm: kimi:kimi-for-coding を指定します。既定のベース URL は https://api.kimi.com/coding/v1 です。Open Platform と Coding Plan のキーは、それぞれに対応するベース URL と組み合わせる必要があります。 旧設定では、明示的に有効化した場合にのみ KIMI_API_KEY と任意の KIMI_BASE_URL が検索の認証情報を提供します。WEB_SEARCH_KIMI_ENABLED=true を設定するか、server-providers.yml に web-search.kimi を追加します（例：enabled: true）。チャットの認証情報だけでは検索は有効にならず、既定の検索プロバイダーも変わりません。スロットに割り当てられていても、WEB_SEARCH_KIMI_ENABLED=false は Kimi 検索を無効にします。WEB_SEARCH_KIMI_ENABLED が Kimi 検索の唯一のスイッチです。 KIMI_MODELS はチャットにのみ適用されます。旧設定のチャットと検索でアカウントが競合すると警告が出て、検索エントリーはスキップされます。別々のアカウントを使う場合は、openmaic.yml で別々のプロバイダー ID を宣言してください。 openmaic.yml が存在する場合は、プロバイダーを宣言してスロットを明示的に割り当ててください。設定と初回起動ウィザードでは、同じアカウントから両方の機能を利用できます。

エンドポイントはベースパスに応じて選択されます。末尾のスラッシュを除いたパスが /coding/v1 で終わる場合は /search、それ以外は /tools/search_pro を使用します。デプロイで設定するカスタムプロキシも、このパス構成を維持する必要があります。ウィザードが検索を推奨するのは公式アカウントのベース URL のみなので、ワークスペースのカスタムチャットプロキシに検索が自動で割り当てられることはありません。

openmaic.yml が存在する場合は、providers.: { preset: kimi } を宣言して slots.webSearch: を割り当ててください。旧環境変数 WEB_SEARCH_KIMI_ENABLED ではこのスロットを割り当てられません。

Webページ取得のプロバイダースロット Copy Chapter

webFetch は、エージェントの fetch_url ツールで使う読み取りサービスを選択します。従来の設定、空の設定、YAML 設定では builtin が既定であり、lock: all でこのルートが未指定の場合も同様です。webFetch: null を明示すると取得が無効になり、以降の実行からツールとそのプロンプトが除かれます。各リクエストは一つのプロバイダーだけを使用し、フォールバックや別サービスへの切り替えはありません。無効なプロバイダー参照やポリシーで拒否されるワークスペースのエンドポイントは、webSearch と同様に、エージェント開始前の機能解決時に実行全体を失敗させます。これは設定エラーであり、fetch_url の失敗結果ではありません。組み込みサービスへの切り替えも行いません。

providers:
  reader:
    preset: kimi
    apiKey: ${KIMI_API_KEY}
    baseUrl: https://api.moonshot.cn/v1
slots:
  webFetch: reader

kimi と kimi-coding-plan の両プリセットが webFetch を提供します。Coding Plan の認証情報には preset: kimi-coding-plan を使います。既定のベース URL は https://api.kimi.com/coding/v1 で、明示したベース URL は保持されます。Moonshot Open Platform のベース URL（https://api.moonshot.cn/v1、https://api.moonshot.ai/v1）には /tools/fetch、Coding Plan には /fetch を使用します。いずれも Bearer 認証で { "url": ... } を含む POST を送ります。アダプターは markdown または content を受け付けます。メンテナーが実際のキーで POST https://api.kimi.com/coding/v1/fetch をテストし、応答に { markdown, title, url } が含まれることを確認しました。国際エンドポイントの利用可否は引き続き未検証です。リクエストはプロバイダーの proxy 設定と標準のプロキシ環境変数に従います。

DeepSeek は deepseek プリセットでホスト型 Markdown 抽出も提供し、チャットのキーと API ベースを共有します。上の例のように webFetch を明示的に割り当てます。/v1/tools/fetch を使い、デプロイで指定したゲートウェイのベースを保持します。タイムアウトと転送エラーのみ 1 回再試行する動作は Kimi と同じで、HTTP エラーや不正な応答は再試行しません。

設定 → モデルサービス → Webページ取得 で既存の認証情報を使用し、コースモデル設定 → Webページ取得 でサービスを選びます。キーは同じプロバイダーのチャットと共有され、変更や削除はチャットにも影響します。管理者が固定したカードは読み取り専用です。初回設定では、別のサービスを明示的に選ぶまで組み込みの既定値を維持します。ワークスペースの認証情報は公式 API のベース URL を使用でき、独自の取得エンドポイントとプロキシは管理者が openmaic.yml に記述する必要があります。

kimi と異なり、firecrawl は専用のキーを使います。openmaic.yml で preset: firecrawl のプロバイダーと apiKey（例: ${FIRECRAWL_API_KEY}）を宣言するか、設定 → モデルサービス → Webページ取得 でキーを入力します。Bearer 認証で POST /v2/scrape を送り、ページの本文を Markdown で取得します。既定のベース URL は https://api.firecrawl.dev です。セルフホストの Firecrawl のベース URL は、管理者が openmaic.yml で宣言する必要があります。

同じ firecrawl プロバイダーは Web 検索（POST /v2/search）にも使えます。1 つのキーとベース URL で両方をまかなうため、1 つのプロバイダーを slots.webSearch と slots.webFetch の両方に割り当てられます。従来の FIRECRAWL_API_KEY と FIRECRAWL_BASE_URL 変数はこのプロバイダーを設定します。webFetch をこのプロバイダーに割り当てるまで、Webページ取得は builtin のままです。

ホスト型サービスに URL を送る前に、セッションの URL 許可、厳密な URL 正規化、ローカル DNS の全アドレス検査を行います。返された最終 URL も、内容を受け入れる前に同じ検査を受けます。ホスト型サービス自身の DNS と中間リダイレクトはサービス側が制御するため、ローカルの検査ではそのネットワーク接続を固定できません。返されたテキストは信頼できないデータのままであり、認証チャレンジページの検出、バイト数制限、切り詰め表示、既存の Web 素材保存と {trusted, untrusted} の結果形式を適用します。

Packages Docs Content Docs Configuration (`packages/docs/content/docs/configuration.mdx`) Copy Section

title: Configuration Copy Chapter

OpenMAIC has three configuration sources, and each has one job:

DATABASE_URL is required; other environment variables are optional (see Deployment). Providers that use server credentials for model selection also need authorized model lists, as described below. See .env.example for environment variables, openmaic.example.yml for a sample model configuration, and Supported models for preset and model IDs.

Earlier releases configured models only through provider environment variables, server-providers.yml, DEFAULT_MODEL and MODEL_ROUTES. Those still work for now, with the exception of MODEL_ROUTES, and are deprecated; see Migrating from the legacy configuration.

Models and providers Copy Chapter

Concepts Copy Section

• Provider: an account the server can call, such as an OpenAI key, a MiniMax token plan or a self-hosted OpenAI-compatible server. Each provider has an id you choose and a preset that says which vendor it is and which capabilities it covers.
• Slot: a use of AI in the product, such as the course outline, slide content, text to speech or web search. Slots form one tree per capability; a slot without an assignment follows its parent.
• Assignment: which provider and model a slot uses (provider:model), optionally with call parameters and a fallback model, or null to turn the slot off.

A capability is available exactly when its slot resolves to an assignment. There are no separate on/off switches.

openmaic.yml Copy Section

The server reads openmaic.yml from the directory it starts in (the repository root; /app in the Docker image). Set OPENMAIC_CONFIG to use another path; a relative path is resolved against the same directory, and the file must then exist. Without the file, the server uses the web settings and, while they are still set, the legacy variables.

The file is read once at startup: restart the server after changing it. It is validated completely before the server starts. An unset ${VAR}, an unknown preset or slot, a reference to a provider that is not declared, or a provider that does not offer a slot's capability stops the server, and each problem is listed with its location:

[boot] Invalid server configuration; the server will not start: Invalid model configuration in /app/openmaic.yml:
  - providers.openai.apiKey: environment variable OPENAI_API_KEY is not set
  - slots.course.outlines: unknown slot

Keep secrets out of the file itself: reference them as ${VAR} and set the variable in the environment. Values that came from a variable are never printed in these messages.

A complete example Copy Section

/* Detailed source-code truncated for AI context efficiency. */

With this file, the slots written under slots are the server's defaults: users may change each of them in the model settings, except tts, which lock fixes for everyone. A chat slot it leaves out, such as course.agents, follows its parent (llm); a capability root it leaves out, such as asr or document, stays unconfigured until a user assigns it. With allowUserKeys: false, users choose only among the providers declared here.

Providers Copy Section

Each entry under providers declares one provider. The key is its id, which slots use in references: 1 to 63 lowercase letters, digits and dashes, starting with a letter or digit.

Most presets cover one capability, following the built-in registries: the openai preset is chat only, and OpenAI images and speech are the openai-image, openai-tts and openai-whisper presets. Declare one provider per capability, and reference the same ${VAR} when one key covers several. Token plan presets (minimax, tokendance, volcengine-ark, kimi-coding-plan) cover several capabilities with one key, each at the plan's own endpoint. A baseUrl on a provider replaces the endpoint for every capability that provider covers, so give a token plan a baseUrl only when all of its capabilities move with it.

Amazon Bedrock (preset: bedrock) signs requests with the AWS credential chain of the server (environment, profile or role) and reads the region from BEDROCK_REGION, AWS_REGION or AWS_DEFAULT_REGION; apiKey is an optional bearer token.

Slots Copy Section

How a slot resolves:

• Resolution starts at the slot of the call and walks up to its capability root. The first assignment found wins, so a parent's assignment is the default for its whole subtree. Changing a parent changes every child without its own assignment.
• Inside a locked subtree (the slot or an ancestor is named by lock, or lock: all), only openmaic.yml counts: the walk goes up to the locked slot and the first assignment the file writes wins. Everywhere else the user's choice wins: the walk first looks for the workspace's own assignment from the slot up to the root, and only when there is none, for the defaults openmaic.yml writes, again from the slot up. So a slot whose server default the workspace has not changed follows the workspace's choice on a parent; server values are only defaults.
• null stops the walk: the slot and every slot below it that has no assignment of its own are off.
• Reaching the root without an assignment leaves the capability unconfigured. Calls fail with an error that names the slot; there is no fallback to any vendor.
• Requirements belong to the slot that declares them and are checked against the model it resolves to, assigned or inherited. agent requires tool calling; if the built-in catalogue says its model lacks it, the agent refuses to run instead of making do. A model the catalogue does not know is allowed. agent.title has no requirement, so it can use a smaller model.

Assignments Copy Section

An assignment has one of four forms:

slots:
  llm: openai:gpt-5.5            # provider:model
  webSearch: tavily              # provider only: the provider's default model
  course.outline:                # an object with parameters
    model: openai:gpt-5.5
    fallback: anthropic:claude-sonnet-4-6
    thinking: { effort: low }
  video: null                    # off

The object form accepts:

The agent slot must not set thinking.effort: its tool-calling transport cannot combine reasoning effort with function tools.

Provider-only references Copy Section

A reference without :model means the provider's default model: the model a token plan recommends for that capability, else the default of the built-in registry. Search and document services mostly have no model to pick, so webSearch: tavily or document: mineru-cloud is the usual form. Chat slots always name a model; llm: openai is refused at startup.

Fallbacks Copy Section

Fallbacks apply to language-model slots: llm and every slot below it. A fallback on a tts, asr, image, video, webSearch, webFetch or document slot is refused, at startup for openmaic.yml and on save in the model settings.

A slot's fallback is tried once when a call on the primary model fails after its own retries with a retryable failure: a transient SDK error, a timeout, a network error, a rate limit (429), capacity (503), or empty output. An explicit quota refusal from the provider (an OpenAI-compatible code such as insufficient_quota, whatever its HTTP status) is not retried on the primary model: the call goes to the fallback at once. Content-safety refusals and other 4xx errors never fall back. The fallback applies to both regular and streaming calls and uses the slot's thinking parameters.

The fallback belongs to the assignment and is inherited with it: course.content.slide without an assignment of its own uses the model and the fallback of course.content. A slot with a requirement does not retry on a fallback that fails it.

Turning a capability off Copy Section

Write null on its slot. video: null turns video generation off by default, and users may still turn it on in the model settings; add lock: [video] to keep it off for everyone. course.content.pbl: null turns off project-based learning scene generation while the rest of course.content keeps working. A call on a slot that is off fails immediately, and the media routes answer 403 instead of choosing another vendor.

Defaults, locks and the model settings Copy Section

What openmaic.yml writes under slots is the server's default: users may change it in the model settings, where the card says Server default, and Reset to server default removes their change. What it names under lock is fixed by the administrator for everyone, together with its whole subtree:

lock: [llm, video]   # these slots and every slot below them
# lock: all          # every slot

• Every slot lock names must be written under slots (null counts: video: null with lock: [video] keeps video off for everyone). An unknown slot, or a locked slot slots does not write, stops the server at startup with its position (lock.1: ...).
• A locked slot fixes its children too: with lock: [llm], no user can set course.outline or any other language model slot, and all of them resolve from openmaic.yml alone.
• lock: all fixes every slot, written or not; a capability root slots leaves out is then unconfigured for everyone. For webFetch, an omitted assignment uses builtin; set webFetch: null to disable it.
• null, a server default and a lock combine as you would expect: video: null alone is off until a user turns it on; with lock: [video] it stays off.

The settings take one of three shapes, derived from the configuration:

One rule decides every control: it is shown only if using it can change something. A Model Services tab, and adding a service there, appears only while its capability has a slot a user may set; Token Plan appears only while a plan can still fill a slot that is not locked, and connecting a plan never touches a locked slot. A locked card in Course Model Config is one read-only line marked Fixed by the administrator. The home page model picker appears only when the default model can be changed (llm is not locked and a provider offers a language model).

The model settings in the web app read and edit the same tree for the current workspace:

• Token Plan: connecting a plan adds its provider with the key and fills the slots the plan recommends that are still unassigned. Disconnecting removes the provider; the slots that used it follow their parents again.
• Model Services: one tab per capability (language models, images, video, text to speech, speech recognition, document parsing, web search) lists its services. Providers from openmaic.yml are shown read-only and without anything about their keys. A service the workspace sets up becomes a workspace provider: its key is write-only and shown only as a mask such as …abcd, a custom endpoint is possible for language models only (Azure Speech takes its official regional endpoint, such as https://<region>.tts.speech.microsoft.com), and self-hosted services and key pairs are configured in openmaic.yml. The test buttons check the saved provider on the server.
• Course Model Config: the main model is the llm slot and each pipeline stage is its own slot (following the main model means the stage has no assignment of its own); the image, video, speech, search and transcription switches set their slot to null. A locked slot is one read-only line, and a slot on a server default offers Reset to server default once a user has changed it.

Provider settings that a browser stored in earlier versions (providers with their keys and base URLs, the chosen model, token plan enrollment and each capability's selection) are imported into the workspace once. The import never replaces an existing workspace setting or a slot in a subtree openmaic.yml locks, and it skips items that allowUserKeys: false or validation refuses. After a 2xx answer, only what the workspace now holds leaves the browser: every item the server skipped (a custom endpoint for a media service, a preset a workspace may not use, a provider id the deployment declares, ...) is kept in this browser with its key, never sent again, announced once, and listed in Settings → Model Services with the reason until it is set up again or discarded. An Azure Speech provider with its regional endpoint is imported. A 400 refuses the whole proposal: it is not sent again, and its items are kept in this browser with their keys and listed like the skipped ones. An unreadable proposal is dropped. The proposal stays in the browser for a later attempt only on 401, 404, 409, a 5xx or a network error. Speech input that was explicitly switched off becomes asr: null, and narration, images or video switched off while a usable provider for them was set up become tts: null, image: null or video: null (a slot openmaic.yml locks is left as it is). These have to be set up again by hand: per-stage models (in Course Model Config, or slots in openmaic.yml), thinking settings (thinking on a slot), custom speech and transcription providers and AliDocMind's key pair (in openmaic.yml; they are kept in the browser and listed with the skipped items), the VoxCPM backend (options.backend), and Baidu search sub-sources (the server's defaults apply). Research switched off is not carried over (it only stopped course research; chat and the agent kept searching), nor is a switch that was off only by default: each capability now runs whenever its slot resolves.

A workspace is an owner in the sense of the persistence documentation: with the default Docker Compose setup (single-user mode) there is one workspace, and in a multi-user deployment each signed-in account has its own.

allowUserKeys Copy Section

allowUserKeys: false

allowUserKeys (default true) decides whether users may add providers, keys and token plans of their own. With false, users only choose among the providers openmaic.yml declares, for the slots it does not lock: Token Plan and adding services are not shown, and providers a workspace added earlier are no longer used. Requests that still name their own model, key or endpoint (the deprecated x-model, x-api-key and x-base-url headers, and the provider fields of the media routes) are ignored then, and the header form of the provider test buttons is refused. A multi-user deployment that pays for all usage typically sets it and locks the slots it wants fixed.

Secrets and OPENMAIC_SECRET_KEY Copy Section

• Keys in openmaic.yml come from the environment through ${VAR}. They are never stored in the database and never sent to the browser.
• Keys a workspace enters in the model settings are stored in the database, encrypted with AES-256-GCM under the instance secret OPENMAIC_SECRET_KEY.
• When OPENMAIC_SECRET_KEY is unset, the server creates a random secret on first use in data/instance-secret.key (inside the openmaic-data volume with Docker Compose) and uses it from then on.

Keep the secret with the database backups: keys saved under a lost or changed secret cannot be read and have to be entered again (the model settings mark them). Set OPENMAIC_SECRET_KEY explicitly when more than one instance shares the database, or when the server has no persistent data directory (a container without the data volume); any string works, for example the output of openssl rand -base64 32.

Without it, a data directory that does not survive a restart (a container without a volume, an ephemeral disk) means a new secret on every start, and several replicas each generate their own; on a read-only working directory no secret can be created and saving a key in the model settings fails. At startup the server warns when OPENMAIC_SECRET_KEY is unset and the data directory is not writable, and when the database holds keys sealed under a different secret than the current one (for example because data/instance-secret.key was lost); it starts anyway.

OPENMAIC_SECRET_KEY=...        # instance secret for keys saved in the model settings
OPENMAIC_CONFIG=/etc/openmaic/openmaic.yml   # optional: another path for openmaic.yml

What workspaces may add Copy Section

Providers from openmaic.yml can be anything the schema accepts. Providers a workspace adds in the model settings are more restricted, because their endpoint and key are typed by a user of the web app:

• Amazon Bedrock is not offered: it would sign with the server's own AWS credentials.
• No proxy, and no key pairs (credentials): presets that authenticate with a key pair, such as AliDocMind, are deployment-only.
• A custom baseUrl is allowed only for presets that offer chat, and a provider with one serves chat slots only. The URL must not contain credentials, a query string or a fragment, and must resolve to a public address unless the server sets ALLOW_LOCAL_NETWORKS=true. Requests to it do not follow redirects.
• Local model servers (Ollama, Lemonade) must name their own endpoint rather than use the preset's localhost default.
• Self-hosted media, search and document services (VoxCPM2, FunASR, Lemonade speech and images, ComfyUI, SearXNG, self-hosted MinerU) run on the server's own network and are deployment-only.
• Providers the operator switched off with a legacy <CAP>_<VENDOR>_ENABLED=false variable are not offered.
• A workspace cannot declare a provider id that openmaic.yml already declares.

A deployment that wants users to reach internal services declares those providers in openmaic.yml.

API clients and deprecated request fields Copy Section

Generation requests no longer need to carry keys or model choices: browserless API calls such as /api/generate-classroom resolve through the same slots as the web app, for the workspace of the caller.

The older request headers x-model, x-api-key, x-base-url, x-provider-type, x-model-routes, x-image-provider, x-image-model, x-video-provider and x-video-model, and the equivalent body fields of the speech, search and document routes, are deprecated. They are honoured only while the slot they would affect has nothing assigned or, on a server still configured through the legacy variables, only a default those translate to (as DEFAULT_MODEL always ranked below the model a request named); a default in openmaic.yml, the workspace's own choice and a locked slot win, and a slot set to null refuses the request whatever it names. With allowUserKeys: false they are ignored altogether. The server logs a warning the first time a request uses them. They will be removed two minor versions after the model settings described above ship.

Migrating from the legacy configuration Copy Section

When openmaic.yml is absent, the server translates the legacy configuration at startup and logs a deprecation notice, plus a notice for each entry that could not carry over:

When openmaic.yml exists, the provider variables, server-providers.yml, DEFAULT_MODEL, MODEL_FALLBACK and MODEL_ROUTES are ignored for model resolution, with a notice. <CAP>_<VENDOR>_ENABLED=false still applies; to turn a capability off, set its slot to null instead.

Environment variables. Before:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DEFAULT_MODEL=openai:gpt-5.5
MODEL_FALLBACK=anthropic:claude-sonnet-4-6
TTS_MINIMAX_API_KEY=...
TAVILY_API_KEY=tvly-...

After (the keys stay in the environment):

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}
  anthropic:
    preset: anthropic
    apiKey: ${ANTHROPIC_API_KEY}
  minimax-tts:
    preset: minimax-tts
    apiKey: ${TTS_MINIMAX_API_KEY}
  tavily:
    preset: tavily
    apiKey: ${TAVILY_API_KEY}

slots:
  llm:
    model: openai:gpt-5.5
    fallback: anthropic:claude-sonnet-4-6
  tts: minimax-tts
  webSearch: tavily

Remove DEFAULT_MODEL and MODEL_FALLBACK afterwards. The provider variables can stay as the source of the ${VAR} references. A _BASE_URL becomes the provider's baseUrl (OPENAI_BASE_URL → baseUrl under openai; write the URL, or ${OPENAI_BASE_URL} while the variable stays set), and _MODELS becomes its models list. As with the translated DEFAULT_MODEL, the llm written here is a server default workspaces may change; add lock: [llm] to fix it for everyone. Unlike the translation, agent now follows llm: write agent: null to keep the Pro agent off.

server-providers.yml. Before:

providers:
  azure:
    apiKey: ...
    baseUrl: https://YOUR-RESOURCE.openai.azure.com/openai
    models: [my-deployment]
pdf:
  alidocmind:
    accessKeyId: ...
    accessKeySecret: ...
web-search:
  searxng:
    baseUrl: http://searxng:8080

After:

providers:
  azure:
    preset: azure
    apiKey: ${AZURE_OPENAI_API_KEY}
    baseUrl: https://YOUR-RESOURCE.openai.azure.com/openai
    models: [my-deployment]
  alidocmind:
    preset: alidocmind
    credentials:
      accessKeyId: ${ALIDOCMIND_ACCESS_KEY_ID}
      accessKeySecret: ${ALIDOCMIND_ACCESS_KEY_SECRET}
  searxng:
    preset: searxng
    baseUrl: http://searxng:8080

slots:
  llm: azure:my-deployment
  document: alidocmind
  webSearch: searxng

Each section of server-providers.yml becomes providers with the matching preset (providers → chat presets, tts, asr, pdf → document, image, video, web-search), and accessKeyId/accessKeySecret move under credentials.

MODEL_ROUTES. A server that sets MODEL_ROUTES without openmaic.yml does not start:

MODEL_ROUTES does not carry over to the model configuration: write the per-stage models as slots in openmaic.yml (or the file named by OPENMAIC_CONFIG) and remove MODEL_ROUTES

Per-stage routes do not map one to one onto slots, so they are not translated. Rewrite each route as the slot its stage belongs to:

Several stages share a slot: give the slot the one model they should use. A route's thinking moves to the slot's thinking, and a maic-agent-driver route's api and contextWindow move to the agent slot. Before:

DEFAULT_MODEL=openai:gpt-5.5
MODEL_ROUTES='{"scene-outlines-stream":"anthropic:claude-sonnet-4-6","scene-content:slide":{"model":"openai:gpt-5.4","thinking":{"effort":"low"}},"maic-agent-driver":{"model":"openai:gpt-5.5","api":"openai-completions"}}'

After:

providers:
  openai:
    preset: openai
    apiKey: ${OPENAI_API_KEY}
  anthropic:
    preset: anthropic
    apiKey: ${ANTHROPIC_API_KEY}

slots:
  llm: openai:gpt-5.5
  course.outline: anthropic:claude-sonnet-4-6
  course.content.slide:
    model: openai:gpt-5.4
    thinking: { effort: low }
  agent:
    model: openai:gpt-5.5
    api: openai-completions

Once openmaic.yml exists, the provider variables configure nothing on their own: a TTS, image, document or web search provider that had only its variables (TTS_MINIMAX_API_KEY, IMAGE_SEEDREAM_API_KEY, PDF_MINERU_BASE_URL, TAVILY_API_KEY, …) is no longer used, and other capabilities get no default provider. Declare each provider you use under providers and assign tts, image, document, webSearch (and asr, video) in slots, as in the environment-variable example above; a slot for another capability left unassigned stays unconfigured unless a workspace assigns it in the model settings.

Then remove MODEL_ROUTES, DEFAULT_MODEL and MODEL_FALLBACK.

Docker. Mount the file next to the app and keep the keys in .env.local:

services:
  openmaic:
    volumes:
      - ./openmaic.yml:/app/openmaic.yml:ro

ACCESS_CODE — site-wide password Copy Chapter

For shared deployments such as internal demos or classrooms, set an access code so visitors must enter a password before they can see the app:

ACCESS_CODE=your-secret-code

Use a long random value (at least 16 characters) — this code is the only secret guarding the deployment. 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 proxy that overwrites x-forwarded-for / x-real-ip: each client gets 10 attempts per 60 seconds, and a successful verification clears that client's counter. Without a trusted proxy the app cannot attribute a request to a client, so there is no throttle; rely on the length and randomness of the code. Leave it empty to disable access control.

Feature flags Copy Chapter

Feature flags accept true or 1; unless noted otherwise, all other values are treated as disabled. NEXT_PUBLIC_* flags are injected into the client at build time, so changing them requires a rebuild:

# MAIC Editor (Pro mode)
NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true

# PPT and Interactive courseware references in Pi playback (build-time; editor references are separate)
NEXT_PUBLIC_COURSEWARE_REFERENCE_ENABLED=true

# Vocational education task engine (server-side flag)
OPENMAIC_ENABLE_VOCATIONAL=true

# Show the vocational education experimental switch
NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI=true

# Show the video export entry point
NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true

# Show the experimental PPTX import entry point
NEXT_PUBLIC_ENABLE_PPTX_IMPORT=true

Classroom chat always runs on Pi, which requires a model with tool (function) calling: select one for Classroom in Course Model Config, or set the classroom slot (or the llm slot it inherits from) in openmaic.yml. For Gemini, use the native google preset rather than Google's OpenAI-compatible endpoint. It refuses a model that the built-in catalogue lists without tool calling before inference, with 400 MODEL_CONFIG_INVALID (reason: tool_calling_required), and Course Model Config notes the requirement on the classroom slot.

The old director-graph classroom chat has been removed, and NEXT_PUBLIC_PI_CHAT_ENABLED no longer selects a chat path. Remove it from your configuration: a production build accepts only unset, an empty string, true or 1 (exact match) and fails with migration guidance on any other value. With Docker Compose, the service env_file (.env.local) supplies runtime values, not build args.

PPTX import is still experimental, and its parsed output is not yet fully integrated into the classroom data flow. All NEXT_PUBLIC_* variables above are build-time flags. Docker deployments must also pass them as build args; setting them only as container runtime environment variables is not sufficient.

Other server options Copy Chapter

The following server options can also be configured with environment variables:

# Parallel scene-content generation; 0 or unset means sequential
PARALLEL_SCENE_CONCURRENCY=3

# Allow localhost and private-network addresses; self-hosted/private deployments only
ALLOW_LOCAL_NETWORKS=true

# Optional MP4 rendering service
RENDER_SERVICE_URL=http://render-service:9000

# Logging and reasoning
LOG_LEVEL=info
LOG_FORMAT=pretty
LLM_THINKING_DISABLED=false

Legacy provider environment variables Copy Chapter

These variables and server-providers.yml are the configuration of earlier releases. They still work when there is no openmaic.yml (see Migrating from the legacy configuration) and are deprecated: they will be removed two minor versions after the model settings ship. With openmaic.yml, use them only as the source of ${VAR} references. DEFAULT_MODEL and MODEL_FALLBACK are covered in the migration section; MODEL_ROUTES is no longer read.

LLM providers Copy Section

Cloud providers generally use three environment variables: an API key, a base URL, and a model list. The API key is usually required; the base URL and model list are optional. Azure OpenAI requires a resource endpoint, while Ollama and Lemonade do not require an API key.

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=                # optional base URL override
OPENAI_MODELS=                  # optional model allowlist (comma-separated)

Supported provider prefixes: