Docker Deployment

Updated: 07/30/2026Word count: 0 wordsReading time: 1 min

Prerequisites

MaiBot Docker deployment requires Docker and Docker Compose, plus at least 2GB of available memory. It supports Linux, macOS, and Windows (via Docker Desktop).

First, verify your environment:

docker --version
docker compose version

If not installed yet, refer to the official docs:

• Docker — Official Installation Docs
• Docker Compose — Official Installation Docs

Domestic Users (China)

For servers in China, you can use this one-liner:

bash <(curl -sSL https://linuxmirrors.cn/docker.sh)

Docker Compose

This is the recommended deployment method.

Using the Official docker-compose.yml

The MaiBot repository provides a complete docker-compose.yml. Download it directly:

curl

curl -o docker-compose.yml https://raw.githubusercontent.com/Mai-with-u/MaiBot/main/docker-compose.yml

wget

wget -O docker-compose.yml https://raw.githubusercontent.com/Mai-with-u/MaiBot/main/docker-compose.yml

The official configuration includes MaiBot core, NapCat, and database tools, suitable for most users.

Using the Minimal Configuration

If you only need the MaiBot core without NapCat and database tools, use this minimal configuration:

docker-compose.yml

services:
  core:
    container_name: maim-bot-core
    image: sengokucola/maibot:latest
    environment:
      - TZ=Asia/Shanghai
      - EULA_AGREE=8e6e7d647f7f82d6ea98456b73908656
      - PRIVACY_AGREE=91e5db7659c560bc3545e63859b6ebc0
      - WEBUI_HOST=0.0.0.0
    ports:
      - "18001:8001"
    volumes:
      - ./docker-config/mmc:/MaiMBot/config
      - ./data/MaiMBot:/MaiMBot/data
      - ./data/MaiMBot/plugins:/MaiMBot/plugins
      - ./data/MaiMBot/logs:/MaiMBot/logs
    restart: always

Start

Bash

docker compose up -d

The first launch will automatically generate configuration files.

Data Storage Locations

• Configuration files — ./docker-config/mmc/
• Runtime data — ./data/MaiMBot/
• Plugins — ./data/MaiMBot/plugins/
• Logs — ./data/MaiMBot/logs/

Port Reference

• WebUI — 18001 (mapped to 8001 inside the container)

WARNING

The default WebUI host is 127.0.0.1, which inside a Docker container means only the container itself can access it. When deploying with Docker, make sure to change host to 0.0.0.0.

TIP

If your server has the standalone Docker Compose installed, the command should be docker-compose (with a hyphen) instead of docker compose.

Direct Docker Image Deployment

If you just want to quickly pull and run the image without modifying any configuration, use this method:

Bash

docker pull sengokucola/maibot:latest

Then run the container directly:

Bash

docker run -d \
  --name maim-bot-core \
  -p 18001:8001 \
  -e TZ=Asia/Shanghai \
  -e EULA_AGREE=8e6e7d647f7f82d6ea98456b73908656 \
  -e PRIVACY_AGREE=91e5db7659c560bc3545e63859b6ebc0 \
  -e WEBUI_HOST=0.0.0.0 \
  -v ./docker-config/mmc:/MaiMBot/config \
  -v ./data/MaiMBot:/MaiMBot/data \
  -v ./data/MaiMBot/plugins:/MaiMBot/plugins \
  -v ./data/MaiMBot/logs:/MaiMBot/logs \
  --restart always \
  sengokucola/maibot:latest

This method only starts the MaiBot core. If you also need NapCat and database tools, use Docker Compose deployment instead.

Building from Source with Docker

If you need to modify the source code, or cannot pull images directly from Docker Hub, you can build locally:

git clone https://github.com/Mai-with-u/MaiBot.git

Enter the folder and build the image:

Bash

docker build -t maibot .

To run the container, the command is the same as direct image deployment, just replace the image name with the locally built maibot:

Bash

docker run -d \
  --name maim-bot-core \
  -p 18001:8001 \
  -e TZ=Asia/Shanghai \
  -e EULA_AGREE=8e6e7d647f7f82d6ea98456b73908656 \
  -e PRIVACY_AGREE=91e5db7659c560bc3545e63859b6ebc0 \
  -e WEBUI_HOST=0.0.0.0 \
  -v ./docker-config/mmc:/MaiMBot/config \
  -v ./data/MaiMBot:/MaiMBot/data \
  -v ./data/MaiMBot/plugins:/MaiMBot/plugins \
  -v ./data/MaiMBot/logs:/MaiMBot/logs \
  --restart always \
  maibot

Accessing WebUI

After starting, MaiBot automatically launches the WebUI service. Open your browser and visit the following address (replace 本机IP with your server address; use localhost if running locally):

http://本机IP:18001

On first launch, the container log will print the WebUI login Token, like this:

07-30 18:53:45 [WebUI] WebUI 配置文件不存在，正在创建: /MaiMBot/data/webui.json
07-30 18:53:45 [WebUI] WebUI 配置已保存到: /MaiMBot/data/webui.json
07-30 18:53:45 [WebUI] 新的 WebUI Token 已生成: QSwgc2Vu...
07-30 18:53:45 [WebUI应用] 🔑 WebUI 登录 Token: 5YWz5rOo5Y+v5LmQ5Za1fiDlhbPms6jlj6/kuZDosKLosKLllrXvvIE=
07-30 18:53:45 [WebUI应用] 💡 请使用此 Token 登录 WebUI
07-30 18:53:45 [WebUI服务] 🌐 WebUI 服务器启动中...

Use this command to view container logs:

Bash

docker compose logs core

Copy the Token from the log and paste it into the browser login page to access WebUI. You can later view or modify the Token in data/webui.json.

Once in WebUI, follow the configuration wizard to set up models and connect platforms.

For detailed steps on configuring models and connecting QQ, refer to Model Configuration and Adapters.