MaxKB

Last reviewed Aug 26, 2026 · 776 words

One container, one command, and about 30 minutes from nothing to a chat widget on your own site that answers questions from your own documents. That is what MaxKB is built for, and it delivers it more directly than any other self-hosted RAG tool I have tried. The trade is depth: the moment you want custom chunking logic, complex agent graphs or fine control over retrieval, you have outgrown it, and Dify or RAGFlow take over. For an internal helpdesk bot, a docs assistant or an "ask our policies" tool for a small team, MaxKB is the right size.

The one command

docker run -d --name maxkb --restart unless-stopped \
  -p 8080:8080 -v ~/.maxkb:/var/lib/maxkb 1panel/maxkb

Open port 8080, log in as admin with the default password MaxKB@123.., and change it before doing anything else. The image bundles Postgres with the pgvector extension, so there is no separate database to run; the /var/lib/maxkb volume holds everything. The 2 GB RAM floor is honest for the app on its own. Embedding and generation are separate concerns, and where they run decides your real footprint.

Where the models run is your only real decision

MaxKB is a front end; it ships no language model. It talks to OpenAI, Azure OpenAI, Anthropic, Gemini, DeepSeek, Qwen and any OpenAI-compatible endpoint, plus Ollama for local. You register a model in the admin panel, then assign it to an application.

The last row is where I land for most small teams. Embedding 10,000 pages locally takes minutes on a modest GPU, and the chat model only ever sees the retrieved chunks and the question. Read RAG vs fine-tuning if you are tempted to skip retrieval; for a docs bot you should not.

Ingestion decides answer quality

MaxKB accepts PDF, DOCX, Markdown, TXT and HTML, and can crawl a site by URL. It splits documents into chunks, embeds them, and lets you edit individual chunks by hand in the UI. That sounds minor and is the feature that makes the difference: bad splits are the number one cause of wrong answers, and fixing them here takes seconds. Keep chunks in the 300 to 800 token range, attach an example question to key chunks so retrieval matches how users phrase things, and re-run the same 20 test questions after every change.

Workflow mode and the widget

Applications come in two flavours. Simple mode is a prompt, a knowledge base and a model. Workflow mode is a node graph: conditions, multiple knowledge bases, a function node for calling your own API, and reply nodes. It is enough to route billing questions to one document set and technical ones to another, or to look up an order number before answering. It is not a full agent builder, and pretending otherwise leads to frustration; that is the Dify decision point.

Publishing is a script tag or an iframe pasted into any page, giving a floating chat bubble, or the full-page chat URL. Each application also exposes an API key for calling from your own code, and the widget can be limited to approved domains.

The honest limits

The project is young, and its documentation and community are strongest in Chinese, though the UI ships in English and the English docs improve steadily. Deep retrieval customisation (rerankers, hybrid search tuning) is thin compared with RAGFlow. GPL-3.0 is fine for internal use, and the vendor's paid edition signals the free version will stay usable but not always feature-complete. Multi-user works, but as admin-and-users rather than fine-grained roles.

What I'd do

Deploy the one-liner behind a reverse proxy with TLS, change the admin password, wire Ollama for a local embedding model and a hosted chat model with a spend cap. Ingest one product's docs, write 20 test questions, spend an afternoon fixing chunks. Ship the widget to an internal page first. If a month later the team asks for tool calls, branching conversations and a real agent, move to Dify; if they are just asking questions and getting answers, MaxKB is finished and there is nothing more to build. The AI category has the rest of the field.