KoalaQA: a self-hosted AI support community built around a knowledge base

The problem KoalaQA is aimed at

Support forums rot. Someone asks a question, a human answers it, the thread scrolls away, and three months later the same question is asked again by a different person. KoalaQA's pitch is that the answer should be captured as a retrievable pair the first time and reused automatically afterwards. The README frames this around ZCR, Zero Contact Resolution: the share of questions resolved without a human touching them, and it claims the AI handling about 90% of common questions with escalation to a human for the rest. That 90% figure is a vendor claim in the README, not a measured result, and it will depend almost entirely on how much of your traffic is genuinely repetitive.

The intended user is a team that already runs some form of developer or customer community and wants a self-hosted place to put it. The topics list gives it away: faq, forum, knowledgebase, question-answering, rag, support. If your support load is a handful of emails a day, the install and the model bill are not worth it. If you are answering the same twenty questions in a chat channel every week, the knowledge-curation loop is the part that earns its keep.

How the answering path actually works

The README describes the mechanism in one paragraph: in the bot scenario, the model retrieves relevant content from the knowledge base, summarises it, and answers from that retrieval result. That is a standard RAG loop, and the phrase the README uses for the constraint is that the retrieval result keeps the content boundary. In practice that means the bot is scoped to what you have imported, not to the open web. It also means the quality ceiling is your imported material, not the model.

The knowledge base is not static. The feature list describes automatic generation of question-answer pairs that the system then learns from, automatic refinement of answers, and detection of knowledge gaps that it flags for you to fill. That gap detection is the most consequential part of the design, because it turns an unanswered question into a backlog item rather than a silent failure. The README does not describe how a gap is detected or scored, and that is the first thing I would want to see in the documentation before trusting the loop.

Around the answering layer sits a conventional community: multiple boards with independently configured access and visibility, so different teams or product lines can have separate spaces. Authentication supports WeCom QR login, WeChat QR login and OIDC. The stack badges indicate Go 1.22+, React 18+, TypeScript 5.8.3+ and Docker support, so the backend and frontend are separate services behind one install.

Installing it: one script, then a model

The documented path is a single command run as root on a Linux host with Docker 20.x or newer:

bash -c "$(curl -fsSL https://release.baizhi.cloud/koala-qa/manager.sh)"

The script prompts for options and takes several minutes. Note what this is: piping a remote shell script from a vendor-controlled domain into bash as root. The repository is on GitHub, but the installer is not served from GitHub. If you need a reviewable install, that is the gap to close first, and the README offers no alternative path such as a compose file checked into the repo.

When it finishes, the terminal prints the internal and external access URLs on port 443, plus a generated admin username, email and password. You log in with the email and password, not the username.

The first login forces an AI model configuration step. The README is explicit that without a model attached the product will not function. It recommends the vendor's own model marketplace, baizhi.cloud, which grants a small credit on registration. Nothing in the README says a self-hosted or third-party OpenAI-compatible endpoint is supported, so treat model provider flexibility as unverified until you read the model configuration page. After that you import knowledge, configure board categories, registration and login methods, and notification settings.

AGPL-3.0 is the real adoption decision

The licence section states the project uses GNU Affero General Public License v3.0 and spells out the consequences: you may use, modify and distribute the software; modifications must be released under the same licence; and if you provide the software as a network service, you must open-source your code. Commercial use is permitted but carries the same open-source obligations.

For a support community this matters more than it does for a library. KoalaQA is meant to sit on a public domain answering your customers. AGPL section 13 is exactly the clause that reaches that deployment. If you fork it, restyle it, and add a private integration with your billing system, the copyleft question is not hypothetical. I am not giving legal advice, and the README's own summary is a simplification of the licence text, so read the actual AGPL-3.0 terms with whoever handles this at your company. What I can say is that the licence is stated clearly in the README, which is better than the repository metadata suggests: the GitHub licence field came back unknown even though the README names AGPL-3.0.

Where the documentation is thin

Several things an operator needs are absent from the material available here. There are no release tags, so there is no version number to pin, no changelog to read before upgrading, and no way to tell what an update will change. For a service holding your customer conversations, that is a genuine operational risk, not a nitpick.

The README gives no backup or export procedure, no description of where conversation data lives, and no retention controls. It also does not say what happens to imported knowledge when you change models, which matters because the retrieval layer and the summarisation layer are separate concerns and a model swap can change answer quality without any content changing.

The 90% automation figure has no methodology attached. There is no statement of what counts as resolved, whether escalation counts against it, or what corpus it was measured on. Treat it as marketing until you can measure your own resolution rate after importing a month of real questions.

Finally, the community support channel is a WeChat group. If your team does not use WeChat, the practical support path is GitHub issues and pull requests, and the README does not describe a release cadence for either.

KoalaQA against a plain forum plus a bot

The obvious alternative is assembling the same capability yourself: a forum such as Discourse or Flarum, plus a separate RAG service pointed at the same content. The difference is where the loop closes. In a DIY stack, the forum and the retrieval index are two systems, and keeping them in sync is your job: new answers have to be indexed, deleted posts have to be removed from the index, and gap detection has to be built or bought. KoalaQA's claim is that the knowledge base grows out of the community activity itself, with question-answer pairs generated and gaps surfaced inside the same product.

That integration is also the lock-in. With a separate bot you can swap the retrieval layer without touching the forum. Here the answering path, the knowledge store and the boards are one application, and the README describes no export format for the knowledge base. If you later want to leave, the content you care about is the imported knowledge, and there is no documented way to get it out.

A hosted support product is the other comparison, and the trade is straightforward: you give up data residency and pay per seat or per resolution, and in exchange you get a versioned product with a support contract. KoalaQA gives you the server and the responsibility for it.

Maintenance cost and who should run it

Running KoalaQA means owning a Linux host with Docker, a TLS-terminated service on port 443, a model endpoint with its own billing, and the upgrade path for an application with no published releases. The install script handles the first deployment; nothing in the README describes what the second one looks like. That asymmetry is the cost you are signing up for.

It suits a team that already produces support content and wants the community on its own domain, with OIDC wired into an existing identity provider. It does not suit a team whose answers live in private ticket history, because the whole design assumes material you can import into a knowledge base and have a model summarise. It also does not suit anyone who needs a versioned, support-backed product with an SLA.

Before you install, do three checks in this order: read manager.sh before running it as root, confirm on the model configuration page whether a non-baizhi.cloud endpoint is accepted, and read the AGPL-3.0 text against your deployment model. If the third check fails, nothing else in this article matters.

Editorial conclusion

Adopt KoalaQA if you already have a body of support content, want it behind your own domain rather than a vendor's, and can live with AGPL-3.0 on a network-facing service. Do not adopt it if your support answers depend on private ticketing data you cannot publish, or if your legal position forbids copyleft on a customer-facing site. Before installing, verify three things: that the manager.sh script at release.baizhi.cloud is the artefact you intend to run, that the model endpoint you configure is one you are allowed to send customer questions to, and that the AGPL section 13 source-offer requirement is acceptable to whoever owns your public site.

Official sources

1. chaitin/KoalaQA on GitHub
2. Issues
3. Project website
4. README