MaxKB

What it is

MaxKB, short for Max Knowledge Brain, is an open-source platform for building enterprise-grade agents, published on GitHub by 1Panel-dev. You run it on your own server with Docker and build in a web console. It splits and vectorizes your documents, so an agent answers from your files, which the README says cuts down on model hallucinations. A workflow engine, Python tools and MCP tool calls handle jobs with several steps. This listing is Mindket’s setup notes, drawn from the English README and the Chinese manual.

1. You connect a model, local or hosted
2. You upload documents to a knowledge base
3. MaxKB splits and vectorizes them
4. An agent finds the closest segments and answers
5. You publish it as a chat page, an embed or an API

Who it suits

IT teams that want a support agent or a document assistant on their own servers, with the model of their choice. The README names customer service, internal knowledge bases, academic research and education. Every organization named on the docs’ case list is Chinese, from universities and hospitals to an airline and a customs office.

Skip it if you need a manual in English. Beyond the README’s quick start, the docs are in Chinese. Agent access in WeCom, DingTalk or Feishu and the WorkBuddy skill need a commercial edition, and shared resources need the enterprise edition.

Where to use it

MaxKB is a web app on your own server. People reach its agents in a browser, inside your website, through an API or from an AI assistant.

• Linux server: Docker, the offline package (the docs’ pick for production) or the 1Panel app store
• Windows: Docker, with the data in a C:/maxkb folder
• Your website: embed code for a full page or a floating window
• Your own code: each agent’s OpenAI-compatible chat completions URL
• WeCom, WeChat official accounts, DingTalk and Feishu: agent access, an X-Pack feature
• OpenClaw: the MaxKB Skills skill, which lists your published agents and asks them questions
• WorkBuddy: the maxkb-platform-pro skill, on commercial editions only

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with each route’s steps from the README and the docs. The quickest route is one Docker line.

1. Start the container with one line. The README’s command is below. The docs give the same line with registry.fit2cloud.com/maxkb/maxkb, and a form for Windows.
2. Open MaxKB on port 8080. When the container shows as healthy, go to http://your_server_ip:8080.
3. Sign in as admin. The default password is MaxKB@123.., and the 1Panel page says the first sign-in asks you to change it.
4. Add a model. On Models, pick a provider such as Alibaba Cloud Bailian and enter its API key.
5. Build a knowledge base. Pick a vector model, upload your files and wait until each one shows Success.
6. Create an agent and publish it. Link the knowledge base, test it in the preview, then publish.

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

For production the docs recommend the offline package. Upload it to the server, unpack it, and run its script as root. The page’s example version is v2.0.0. Settings such as the port or an external PostgreSQL go in install.conf before you run it.

tar -zxvf maxkb-v2.0.0-x86_64-offline-installer.tar.gz
cd maxkb-v2.0.0-x86_64-offline-installer
bash install.sh

The README adds that users in China whose Docker pull fails should take this offline route. On a server with 1Panel, MaxKB is in its app store under AI / large models.

How to use it

The console’s top bar has five parts: Home, Agents, Knowledge bases, Tools and Models. A simple agent covers most question and answer jobs. An advanced agent is a workflow you draw from components, tools and other agents, for logic such as sorting questions by type or checking for sensitive words.

On the agent’s settings page you pick the model, write the prompts, link knowledge bases and add skills such as MCP servers and tools. Test questions in the preview stay out of the chat logs. Once published, the agent has a public chat link and an embed code for other web systems.

Every agent also takes the OpenAI API format. You call its Base URL plus /chat/completions, with the agent’s API key as a bearer token, and MaxKB gives you both.

Example

Your MaxKB has a published agent named 代码助手 (code helper), and you want OpenClaw to pass questions to it. You cloned MaxKB Skills into OpenClaw’s skills folder and set MAXKB_DOMAIN, a user name and a password in its .env file. In the skill’s folder you run:

python3 scripts/main.py
python3 scripts/main.py "Python 里如何读取文件？" "代码助手"

The first line prints each published agent’s name and description as JSON, the list OpenClaw picks from. The second asks 代码助手 how to read a file in Python. It returns JSON with agent_name and answer, and in the README’s sample the answer points to Python’s built-in open() function.

For newcomers and experts

If you are new. RAG means the agent first searches your documents for the passages closest to a question, then sends them to the model along with the question. Answers stay tied to your files. Start on a test server with Docker, one model key and a simple agent. Upload a few Markdown files and choose smart splitting, which cuts at the Markdown headings. The docs say a TXT or PDF file without # headings is cut every 4,096 characters. When nothing matches, the agent can still ask the model, which the docs say can bring hallucinations, or give a fixed reply you write.

For experts. Retrieval runs as vector search, full-text search, or both with reranking. You set the similarity threshold, how many segments reach the prompt and how many characters they may fill. Question optimization has the model rewrite the question before the search. Advanced splitting takes your own separators, regular expressions included.

Tools are Python functions. Their start parameters, such as an API key, sit apart from the inputs a workflow passes. A new tool starts disabled. A package a tool needs goes in inside the container, with pymysql as the docs’ example.

docker exec -it maxkb bash
pip install pymysql

Triggers run an agent monthly, weekly, daily, at an interval or on a cron expression, or from a webhook with its own URL and bearer token. Agents export to .mk files. For an advanced agent, the file holds every node’s settings and function code, but not the knowledge bases and models its nodes pick. On the offline install, settings live in /opt/maxkb/.env, and mkctl reload applies them. The stack is Vue.js, Django, LangChain and PostgreSQL with pgvector.

Good to know

Your documents, agents and chat logs live on the server you run.

• License: GPL-3.0. CONTRIBUTING.md says contributors agree the producer can make the license stricter or more relaxed, and may use their code commercially, its cloud business included
• Editions: the docs mark the Feishu knowledge base, agent access to chat apps and chat users as X-Pack features, which the professional and enterprise editions carry. Shared resources are an enterprise feature. The WorkBuddy page says the community edition opens only three agent APIs
• Default sign-in: admin and MaxKB@123.. are printed in the public README. Change the password before anyone else can reach port 8080
• Hosted models: the question and the retrieved segments go into the prompt, so they reach the provider. With a model on your own Ollama server, they stay on your machines
• Upgrades: back up first. With Docker, start the new container on the same data folder, or the docs warn the system comes up empty
• Removal: on the offline install, mkctl uninstall removes the service and keeps the data. The pages give no uninstall steps for Docker or 1Panel
• Not run: Mindket read the README and the docs on 3 November 2026 and did not run the commands