OpenMAIC
Deploy OpenMAIC Safely: Providers, Persistence, and Production Checks
A source-backed OpenMAIC deployment guide for Vercel or self-hosting, provider secrets, Postgres persistence, exports, and recovery.
What you will learn
- Choose a deployment shape
- Configure provider and persistence boundaries
- Build a recovery and release gate
Before you start
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Key takeaways
- A UI preview does not prove durable sessions or export recovery.
- Provider capabilities and secrets must be configured and tested independently.
- Pin releases, back up sessions/assets, and review generated learning content.
Pick a deployment shape
The README exposes a Vercel clone path and a self-hosted runtime. For a quick evaluation, Vercel is convenient, but you still need to configure at least one server-side model provider and verify that generated assets and session persistence match your expectations. For a controlled team deployment, pin a release, build from the repository, and keep the runtime and database in the same documented environment.
OpenMAIC's v1.0.0 workbench uses durable, server-backed sessions and a pluggable persistence stack. Treat that as an explicit dependency: a stateless preview can demonstrate the UI, but it cannot prove resume, cancel, or recovery behavior.
Secrets and provider routing
Copy `.env.example` to `.env.local` for local work and configure only the providers you need. The README lists OpenAI-compatible, Anthropic, Google, DeepSeek, Bedrock, local Lemonade, FunASR, and other options; each capability can have its own endpoint and credential. Keep all keys on the server, restrict outbound domains, and use a secret manager in hosted environments.
Test chat, image, speech, search, and storage separately. A successful chat request does not show that exports, audio extraction, or a local provider are configured. Record the selected model and provider in deployment metadata without logging the secret itself.
Persistence, assets, and recovery
Run a small lesson, refresh the browser, restart the service, and resume the session before inviting users. Verify that uploaded materials, generated slides, interactive HTML, and PowerPoint exports land in the intended storage backend with appropriate retention. Back up the database and asset registry, and test restoring a session from a known checkpoint.
If audio or video materials are used, install ffmpeg/ffprobe and configure an ASR provider such as FunASR or Lemonade. When extraction is unavailable, the README says the material should fail with an actionable message; monitor that path instead of accepting an empty transcript.
Release gate
Pin the OpenMAIC commit, Node/pnpm versions, model configuration, and database migration state. Exercise rate limits, oversized documents, provider timeouts, export failures, and cancellation. Require human review for generated educational content and keep a rollback path to the last known-good release.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Choose Vercel evaluation or a pinned self-hosted release.
- 2
Configure server-side provider keys and capability endpoints.
- 3
Exercise persistence, asset storage, exports, restart, and recovery.
- 4
Run failure tests and keep a rollback/review gate.
Copy-ready example
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install
cp .env.example .env.local
# configure one provider, then run the command documented by the pinned releaseFrequently asked questions
Is Vercel enough for production?
It can host an evaluation, but verify database, asset storage, secrets, limits, and recovery before calling it production.
Where should API keys live?
On the server or in a managed secret store; never in client bundles, committed files, or article examples.
Sources
- OpenMAIC README (captured 2026-08-31)Source checked 2026-08-31
- OpenMAIC repositorySource checked 2026-08-31