MaxKB: a GPL-3.0 RAG and agent platform you run in one Docker container

What MaxKB is and which teams it fits

MaxKB expands to Max Knowledge Brain. The README describes it as an open-source platform for building enterprise-grade agents, and lists four target scenarios: intelligent customer service, corporate internal knowledge bases, academic research, and education. Those four have something in common. Each one involves a body of private documents that a general-purpose model has not seen, and each one wants an answer surface that ordinary employees or customers can use without touching a model API.

The project is written in Python and licensed under GPL-3.0. The stack is Vue.js on the front end, Python and Django on the back end, LangChain as the model framework, and PostgreSQL with pgvector for storage. That combination tells you what kind of product this is: a server application with a database, not a library you import. If your team already runs a Django service and a Postgres instance, the operational shape will be familiar. If you were hoping for an SDK you can embed in a Python process, the repository layout (apps/, ui/, installer/, main.py) points the other way.

The RAG pipeline, the workflow engine and MCP tool-use

Three mechanisms sit at the centre of the platform, and the README names all three.

The RAG pipeline handles documents. According to the README, you can upload documents directly or have the system crawl online documents, and it performs automatic text splitting and vectorization. The stated purpose is to reduce hallucinations in large models and improve question answering. Storage for those vectors is PostgreSQL with pgvector, which is why the database choice matters more than it would in a stateless chat product.

The agentic workflow is the second mechanism. The README describes a workflow engine, a function library, and MCP tool-use, aimed at orchestrating AI processes for complex business scenarios. MCP support is visible in the dependency list through langchain-mcp-adapters and the mcp package, so tool calls are wired through the LangChain adapter layer rather than a bespoke protocol implementation.

The third mechanism is integration. The README claims zero-coding integration into third-party business systems, so existing systems can gain question answering without a custom front end. Model support is deliberately broad: private models such as DeepSeek, Llama and Qwen, plus public ones including OpenAI, Claude, Gemini and MiniMax. The dependency list backs this up with langchain-openai, langchain-anthropic, langchain-deepseek, langchain-google-genai, langchain-ollama, langchain-huggingface and langchain-aws. Multi-modal input and output for text, image, audio and video is claimed as native.

The honest reading of that list is that MaxKB is an integration product. Almost every capability it advertises is a wrapper around something else: LangChain for models, LangGraph and deepagents for agent execution, pgvector for retrieval. That is not a criticism. It means the value is in the assembly and the admin surface, and it means the dependency tree is large. The pyproject.toml pins torch, sentence-transformers, numpy and a long tail of vendor SDKs, so the image is not small and upgrades can move several of those pins at once.

Installing MaxKB with Docker and answering your first question

The README gives exactly one installation path: a Docker container. The command starts MaxKB, maps port 8080, mounts a host directory for persistence, and sets the container to restart automatically.

docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb

After that, open http://your_server_ip:8080 in a browser. The README states the default administrator credentials are username admin and password MaxKB@123... Change that password before the instance is reachable from anywhere except localhost.

The README also notes that users in China who hit Docker image pull failures should follow the offline installation document at maxkb.cn/docs/v2/installation/offline_installtion/. That is the only alternative install route the README mentions, and it points at the project's own documentation site rather than a package registry.

For a first real use, the sequence implied by the README is: sign in, add a model provider (for example an Ollama endpoint or an OpenAI key), create a knowledge base, upload or crawl documents so the RAG pipeline can split and vectorize them, then attach that knowledge base to an application. The README does not walk through those screens step by step, so treat the in-product UI as the documentation for that part. If you want to drive it programmatically instead, the repository ships a drf-spectacular dependency, which is the Django REST framework schema generator; the README does not document the API surface itself, so that is something to confirm against the running instance rather than assume.

Where MaxKB gets awkward

The first limitation is licensing, and it is not a small one. GPL-3.0 is a copyleft licence. If you modify MaxKB and distribute it, or distribute a product built on it, the licence terms apply. For an internal knowledge base that never leaves your network, this is usually a non-issue. For a vendor embedding MaxKB in a closed-source commercial product, it is a decision that belongs with counsel, not with the engineering team. The README states the software is distributed on an AS IS basis without warranties.

The second limitation is operational weight. The dependency list includes torch, sentence-transformers, numpy, pypdf, python-docx, openpyxl and a stack of cloud vendor SDKs, alongside Celery, django-celery-beat and django-apscheduler for background work. A single container is the documented deployment, but the runtime footprint is that of a full application server with asynchronous workers and a Postgres database behind it, not a lightweight sidecar.

The third is the boundary of the documentation in this repository. The README covers the value proposition and one install command. It does not document the API, the upgrade procedure, backup and restore, or how the two release lines relate. Three recent releases are listed: v1.10.15-lts and v2.10.5-lts, both from August 2026, and v2.10.4-lts from July 2026. Two LTS lines running at the same time is a real decision point, and the README does not explain which one a new deployment should take. The default branch is v2, which is a hint, not an answer.

Finally, MaxKB is the wrong tool if your problem is small. If you have one FAQ page and one model endpoint, a script that stuffs the page into a prompt will be easier to reason about than a Django application with Celery workers and a vector database. MaxKB earns its complexity when you have many documents, several applications, and non-engineers who need to manage them.

MaxKB compared with Dify, RAGFlow and FastGPT

The three names that come up alongside MaxKB are Dify, RAGFlow and FastGPT, and the differences are in emphasis rather than category. All three occupy the same space: a self-hostable platform that combines retrieval with model orchestration.

Dify is the closest general comparison. It is also a platform for building LLM applications with a visual workflow builder, and it likewise supports multiple model providers. The practical difference to check is deployment shape and licence, because a platform that ships as a set of services behind a compose file asks more of your operations team than a single documented docker run. The related searches include maxkb docker compose, which suggests people are looking for a compose-based deployment; the README in this repository documents only the single-container command, so if compose is what you need, verify it against the project's documentation site rather than the README.

RAGFlow is the retrieval-first option. Its reputation rests on document parsing depth, which is a different bet from MaxKB's. MaxKB's README describes automatic text splitting and vectorization and moves on; a team whose documents are messy PDFs with tables and multi-column layouts should compare parsing quality directly, because that is where retrieval systems are won or lost.

FastGPT is the other Chinese-origin platform in this group, with a similar combination of knowledge base and workflow. Again, the useful comparison is not the feature list, which will look nearly identical across all four, but the licence, the deployment footprint, and how much of the API is documented. MaxKB's advantage in this comparison is the explicit MCP tool-use support and the breadth of model adapters in its dependency list. Its disadvantage is that the README leaves the API, the upgrade path and the two LTS lines unexplained.

Maintenance, releases and upgrade cost

The repository is not archived, and its last push was on 2026-08-11, the same date as the v1.10.15-lts release. That is recent enough that the project is clearly still being worked on, but the README does not describe a support policy, a deprecation window, or how long an LTS line is maintained.

What the release list does show is two parallel LTS lines: v1.10.15-lts and v2.10.5-lts. The pyproject.toml declares version 2.0.0 and requires Python ~=3.11.0, and the default branch is v2. A new deployment that ignores this and starts on the v1 line may find itself needing a migration later, and the README does not document what that migration involves.

Upgrade cost is dominated by the dependency pins. Because the project pins exact versions of Django, LangChain, LangGraph, torch and sentence-transformers, a version bump in the platform can move the model framework and the embedding library at the same time. Anyone running MaxKB in production should be prepared to test a release before rolling it out, and should confirm that the volume mounted at /opt/maxkb holds everything needed to restore the instance.

On licence cost: GPL-3.0 means the source you receive carries obligations if you redistribute modified versions. Internal use, where you neither distribute the software nor a derivative of it, is the straightforward case. Everything else deserves a conversation with someone qualified to give legal advice, which this article is not.

Editorial conclusion

MaxKB fits teams that want a self-hosted RAG and agent platform and accept GPL-3.0, running it from the published container image on port 8080. Teams that need permissive licensing for a closed product, or that only want a thin chat wrapper over one model, should look elsewhere. Before adopting it, change the default admin credentials, confirm the volume mount at ~/.maxkb:/opt/maxkb survives an upgrade, and read the v1.10.15-lts and v2.10.5-lts release notes for the branch you intend to run.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes