octo-server: a Go backend that treats AI agents as chat participants
🐙 The Go backend powering OCTO — an open workplace built for humans × AI agents. REST & WebSocket APIs, Lobster (AI agent) orchestration, and WuKongIM real-time messaging control plane.
At a glance
- What is it?
- Mininglamp-OSS/octo-server is the Go control plane behind the OCTO workplace, wiring REST and WebSocket APIs to a WuKongIM messaging core and an agent runtime called Lobster. It is a platform component, not a drop-in chat server, and the README is honest about the dependency weight.
- Who is it for?
- Adopt octo-server if you are standing up the full OCTO stack and want one Go service to own auth, RBAC, agent sessions and IM fan-out. Do not adopt it if you only need a standalone chat backend or a generic agent framework, because the README ties it to WuKongIM, a MySQL-compatible database and the wider OCTO repo matrix.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem octo-server is built to absorb
Most teams adding an AI assistant to a chat product end up with a second system bolted onto the first. The agent has its own session store, its own routing rules, its own idea of who is allowed to talk to whom. The chat product has another. Keeping those two views of identity and permission in sync is the actual work, and it is the work octo-server is designed to remove.
The README frames the server as the single anchor for the OCTO platform: clients, adapters, task handling, summarisation and the admin console all meet there. The distinguishing claim is that Lobster orchestration is built in rather than added later. The README states that agents are treated as first-class conversation participants, and that routing, session and tool-call execution live in the server. That is a design position, not a feature bullet: an agent is a member of a channel, subject to the same access checks as a human.
Who is this for? Teams that want a self-hosted workplace where a chat client, a task service, an AI summariser and an agent runtime share one authorisation model. If you are building a product where the agent is the product, and chat is incidental, the shape here will feel inverted.
Request flow: authenticate, authorise, execute, fan out, respond
The README lists five steps the server performs per request, and they are worth reading as an architecture summary rather than a slogan.
Authentication accepts a token, a cookie, or a DH-sealed WebSocket frame. That third option matters: the WebSocket path does not simply trust a bearer token presented at connect time, it seals frames. Authorisation is org-aware RBAC plus per-channel ACL plus what the README calls agent-identity gating, meaning the agent's own identity is checked separately rather than inheriting the caller's rights.
Execution runs business logic and may spawn or resume a Lobster agent session. Fan-out then enqueues an IM message through WuKongIM and triggers adapters when a channel needs an external bridge. The response is a unified JSON envelope, or a WebSocket frame, carrying tracing and metrics tags.
The repository layout mirrors this. internal/api holds REST and WebSocket handlers for conversation, user, group, file, org and webhook. internal/service holds access control, Lobster orchestration and IM fan-out. internal/repository holds SQL and cache repositories over MySQL and Redis. internal/im is a control-plane client for WuKongIM covering channel, message and presence. internal/agent holds Lobster routing, the session store and tool-call execution. internal/adapter is the registration and dispatch surface.
The notable boundary is internal/im. The README describes WuKongIM as driven over a thin control-plane boundary so the IM core remains swappable. Thin is the operative word: the server is not in the message delivery path, it tells WuKongIM what to do. That keeps latency off the Go service, and it also means the server's correctness depends on the control-plane API staying stable.
Getting a binary running from the repository
The README gives a four-command path from clone to running process:
git clone https://github.com/Mininglamp-OSS/octo-server.git cd octo-server go build -o octo-server . ./octo-server --config ./configs/tsdd.yaml
The flag is --config and the bundled template is configs/tsdd.yaml. The README states that the default dev config expects a local WuKongIM instance and a MySQL-compatible database, so the binary will build without them but will not be useful until both are reachable. The configs directory is described as holding the YAML config schema plus dev and prod examples, and migrations/ holds the SQL schema migrations. The README does not enumerate the individual YAML keys, so read the template rather than guessing at field names.
Two further documents are named: QUICKSTART.md for an end-to-end walkthrough, and BUILDING.md for cross-repo build notes. The BUILDING.md reference is a signal that a single go build may not be the whole story if you intend to build the surrounding services too.
If you would rather not assemble the dependencies by hand, the README points to Mininglamp-OSS/octo-deployment for a one-command Docker Compose stack covering server, admin, web, matter, smart-summary, WuKongIM, MySQL, Redis, MinIO and nginx. It also states plainly that the older docker/octo/ and docker/tsdd/ compose stacks that used to live in this repository have been retired in favour of that single source of truth. If you find a blog post referencing those directories, it is stale.
Where octo-server is the wrong tool
The dependency surface is the first limitation. The README's own quickstart requires WuKongIM and a MySQL-compatible database before the server does anything useful. There is no documented in-memory or SQLite mode for evaluation. If you want to read the code and run it in an afternoon without standing up two external services, this is not that project.
Second, the scope is a platform, not a library. The README describes octo-server as the anchor that clients, adapters, matter, summary and admin all speak to. Adopting it in isolation means adopting a service whose counterpart repositories (octo-web, octo-admin, octo-matter, octo-smart-summary, octo-lib, octo-adapters) are named in the ecosystem table but not bundled. You can consume the REST and WebSocket APIs from your own client, but you are then responsible for reimplementing whatever the official clients expect.
Third, the agent layer is not a general-purpose agent framework. internal/agent is described as Lobster routing, session store and tool-call execution, and Lobster is defined in the README as OpenClaw-powered. If your agents run on a different runtime, the orchestration code here is closer to a reference implementation than a drop-in engine.
Finally, the README does not document its scaling model, its message-delivery guarantees, or what happens to an in-flight Lobster session when the server restarts. Those are reasonable things to want to know before trusting the service with production conversations, and the supplied material does not answer them.
How this differs from Mattermost or a plain chat backend
The closest comparison in kind is a self-hosted team chat backend such as Mattermost, which also ships a Go server, REST and WebSocket APIs, and a plugin surface. The difference in approach is where the agent sits. In a plugin-oriented chat server, an agent is an integration that authenticates as a bot user and receives events through the plugin or webhook API. Identity and permissions for the bot are the bot's own problem.
Here the agent is inside the authorisation pipeline. The README's request flow puts agent-identity gating in the same step as org-aware RBAC and per-channel ACL, and internal/agent owns session state and tool-call execution rather than delegating it to an external process. That is a deeper coupling and it buys a consistent permission model across humans and agents. It costs you the ability to swap in a different agent runtime without touching server code.
A second contrast is the messaging core. A conventional chat backend owns message storage and delivery. octo-server delegates that to WuKongIM and keeps only a control-plane client. The README presents this as making the IM core swappable. It also means the operational burden of real-time delivery, presence and channel state lands on a separate project with its own release cadence, and the supplied material does not describe how version compatibility between the two is enforced.
Release cadence, licence and the cost of staying current
The release history shows v1.16.0, v1.17.0 and v1.18.0 on consecutive weeks in late August and early September, with the most recent push shortly after v1.18.0. A weekly minor cadence is a real maintenance commitment for anyone tracking it. It usually means the API surface is still moving, and the README's philosophy section reinforces that framing: every open-source cut is shipped as a self-contained product, with one squash per release.
One squash per release has a practical consequence for operators. You cannot easily cherry-pick a single fix across versions, because the release is a squashed commit rather than a readable history of individual changes. Upgrading means moving between release tags, and the material provided does not include a changelog or migration notes, so the cost of a version bump is not something you can estimate from this repository description alone. The migrations/ directory implies schema changes are versioned, which is the part you most need to plan for.
The licence is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files and state significant changes. This is a description of the licence text, not legal advice; if you are embedding octo-server in a product, have counsel review the NOTICE and attribution requirements for your distribution model. The README also states the project carries no internal baggage, which is a claim about provenance rather than a legal term.
Who should take this on, and what to confirm first
Take it on if you are building or operating the OCTO platform itself, or a workplace product that genuinely needs agents to hold the same identity and channel permissions as people. The five-step request flow, the internal/agent package and the WuKongIM control plane are a coherent answer to a specific problem, and the Apache-2.0 licence gives you room to modify it.
Do not take it on if you want a chat server you can run with one binary, or if your agents live on a runtime other than OpenClaw and you have no intention of adapting internal/agent. The README's own quickstart makes WuKongIM and a MySQL-compatible database prerequisites, and the surrounding repositories are part of the intended deployment, not optional extras.
Before committing, confirm three things against the repository rather than this description. First, open configs/tsdd.yaml and check that its WuKongIM endpoint, database and Redis settings map onto infrastructure you already run. Second, read QUICKSTART.md and BUILDING.md to see whether the cross-repo build path matches how you build Go services. Third, check whether migrations/ contains a forward-only path from the schema version you would start at, since the weekly release cadence means the schema is the part most likely to move under you.
Editorial conclusion
Adopt octo-server if you are standing up the full OCTO stack and want one Go service to own auth, RBAC, agent sessions and IM fan-out. Do not adopt it if you only need a standalone chat backend or a generic agent framework, because the README ties it to WuKongIM, a MySQL-compatible database and the wider OCTO repo matrix. Verify first that configs/tsdd.yaml matches your WuKongIM endpoint and database, and read QUICKSTART.md and BUILDING.md before writing your own deployment.
Community notes