AstrBot: a self-hosted chatbot framework that connects LLM providers to your chat apps

What AstrBot actually assembles

Most chatbot projects solve one slice of the problem. AstrBot solves the wiring. The README describes it as an "open-source all-in-one Agent chatbot platform that integrates with mainstream instant messaging apps", and the repository layout backs that up: astrbot/ holds the Python package, dashboard/ holds the WebUI, and compose.yml sits next to a Dockerfile and a k8s/ directory.

The intended audience is stated plainly in the README: individuals, developers and teams building a personal AI companion, customer service, an automation assistant or an enterprise knowledge base. The common thread is that all of these need the same three things connected: a model endpoint, a chat platform, and somewhere to put custom logic. AstrBot's answer is to ship all three in one process, with a plugin system on top.

That framing has a cost. A framework that spans fourteen messaging platforms and roughly two dozen model services carries a large dependency list. The requirements.txt file alone pulls in aiocqhttp, anthropic, openai, google-genai, dashscope, lark-oapi, slack-sdk, python-telegram-bot, py-cord, wechatpy, dingtalk-stream, faiss-cpu, jieba, sqlalchemy and more. You are installing the union of every adapter, not the subset you use.

How the pieces connect at runtime

The dependency list reveals the architecture more clearly than any diagram would. Platform SDKs (aiocqhttp for OneBot v11, python-telegram-bot, lark-oapi, slack-sdk, py-cord, dingtalk-stream, wechatpy) sit on one side. Model SDKs (openai, anthropic, google-genai, dashscope) sit on the other. Between them are the pieces that make it a framework rather than a script: fastapi and quart for HTTP surfaces, sqlmodel and sqlalchemy[asyncio] over aiosqlite for persistence, apscheduler for timed jobs, mcp for tool calling, and faiss-cpu with rank-bm25 and jieba for retrieval over a knowledge base.

So the data flow is: an inbound message arrives through a platform adapter, the core resolves which persona, plugins and context apply, retrieves anything relevant from the knowledge base, calls the configured model service, and routes the reply back through the same adapter. The README lists auto context compression and persona settings as features, which means the context assembly step is doing real work rather than forwarding raw history.

Two details are worth noting. The MCP dependency is pinned as mcp>=1.8.0,<2, so the project tracks the 1.x line deliberately. And the Dockerfile installs nodejs alongside Python, because plugin installation at runtime needs a JavaScript toolchain. That is a heavier image than a pure Python service would produce.

Installing AstrBot with uv and running it once

The README's quickest path assumes you already have uv. It gives a three-command sequence, and the middle command is explicitly first-run only:

uv tool install astrbot --python 3.12
astrbot init # Only execute this command for the first time to initialize the environment
astrbot run

After astrbot run, the service starts and the WebUI is reachable on port 6185, which is the port the Dockerfile exposes and the port compose.yml maps. The README also notes that macOS users may wait 10 to 20 seconds on the first run because of security checks.

Upgrades go through the same tool:

uv tool upgrade astrbot --python 3.12

If you prefer containers, the repository ships a compose file. It uses the published image, mounts a data directory, and maps the WebUI port plus an optional OneBot v11 websocket port:

services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    security_opt:
      - no-new-privileges:true
    ports:
      - "6185:6185" # AstrBot WebUI
      - "6199:6199" # Optional. OneBot v11 Napcat Websocket Port
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/AstrBot/data

The README points to the official documentation for the full Docker procedure rather than reproducing it, so treat the compose file as the starting point and the docs as the reference. Note the timezone variable: it is set to Asia/Shanghai, and scheduled tasks will run in whatever zone you leave there.

Where AstrBot gets in your way

The most concrete limitation is in the platform table itself. Adapters are labelled Official or Community. Matrix, Rocket.Chat and VoceChat are Community, meaning a third-party repository maintains them, and WhatsApp is listed as Coming Soon. If your organization runs on Matrix, you are depending on code the core team does not maintain, and an upgrade of AstrBot can break it without anything in the release notes.

The second constraint is Python 3.12. Both pyproject.toml and the Dockerfile fix that version, and the uv commands pass --python 3.12 explicitly. There is a conditional dependency on audioop-lts for Python 3.13 and later, and python-ripgrep is pinned below 3.14, so the project is aware of newer interpreters but the documented path is 3.12.

The third is the agent sandbox. The README describes it as providing "isolated, safe execution of code, shell calls, and session-level resource reuse", and aiodocker appears in the dependency list, which suggests container-based isolation. The compose file sets no-new-privileges:true on the AstrBot container itself. If you plan to let the agent execute shell commands, that is the feature to validate in your own environment first, because the README does not document what happens when the sandbox runtime is unavailable.

Finally, weight. Installing every adapter means you carry libraries for platforms you will never connect. A single-purpose Telegram bot built on python-telegram-bot directly will be a fraction of the size.

AstrBot against wiring adapters yourself

The realistic alternative is not another all-in-one bot platform. It is writing a thin service yourself: python-telegram-bot or slack-sdk on the inbound side, the openai or anthropic client on the outbound side, and a few hundred lines of glue. That approach gives you exactly the dependencies you need and nothing else.

The difference is where the work lands. A hand-rolled bot has no WebUI, no plugin marketplace, no persona configuration screen, no knowledge base with faiss-cpu and jieba behind it, and no MCP tool layer. You build context compression yourself or you do not have it. AstrBot's bet is that the configuration surface is worth more than the dependency weight, and for anyone connecting more than one platform that bet is reasonable, since the second adapter is nearly free.

It flips if you need exactly one platform and one model. At that point you are paying for a framework to avoid writing glue code you would write once.

Licence and the cost of staying current

AstrBot is AGPL-3.0-or-later according to pyproject.toml, and the repository also carries an EULA.md and FIRST_NOTICE files in several languages. AGPL-3.0 is a network copyleft licence: if you modify AstrBot and let users interact with it over a network, the licence's terms attach to your modified version. That matters most if you fork the core and run it as a service. Using it unmodified, or writing plugins against its plugin API, is a different question, and the repository's own EULA and licence text are what you should read rather than a summary.

The maintenance picture is straightforward from the release history. The last push to the default branch was on 2026-08-19, and releases arrived weekly in the run-up to it: v4.27.2 on 2026-08-05, v4.27.3 on 2026-08-12, v4.27.4 on 2026-08-19. The repository is not archived. That cadence cuts both ways. Security fixes and platform API changes land quickly, but so do upgrades you have to absorb, and a plugin written against one minor version may need attention at the next. Running the Docker image with latest as the tag, as compose.yml does, means you take every release whenever you pull. Pinning a version tag is the obvious mitigation, and the project publishes per-version tags.

Editorial conclusion

AstrBot fits teams that already run a chat platform and want a self-hosted bot service wired to OpenAI-compatible, Anthropic, Gemini, DeepSeek or Ollama endpoints. It is the wrong pick if you need a hosted SaaS with no server, or if AGPL-3.0 obligations conflict with how you ship your own code. Before committing, verify the uv install path on Python 3.12, confirm your platform adapter is marked Official rather than Community in the README table, and check that the sandbox works in your environment if you plan to let the agent run shell commands.

Frequently asked questions

Official sources

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