Mininglamp-OSS/octo-server: the Go backend behind OCTO's human-plus-agent workplace

What octo-server actually is, and who it is for

The README describes octo-server as "the heart of the OCTO platform": a Go service that exposes REST and WebSocket APIs consumed by octo-web and octo-admin, runs business logic and Lobster agent scheduling, and acts as the control plane for WuKongIM. OCTO itself is positioned as "the open workplace built for humans x AI agents", with Lobster agents described as OpenClaw-powered digital doubles.

The intended audience is narrow and specific. This is not a chat server you install to talk to friends. It is the backend of a multi-repository product: clients in TypeScript, Kotlin and Swift, an admin console, a task service, a summarisation service, shared Go libraries, and adapter integrations all sit around it. If you are evaluating octo-server on its own, you are evaluating one node of a graph, and the README's own module table makes that explicit.

The design claim worth noting is that agents are treated as first-class conversation participants rather than an add-on. The repository layout backs this up: there is a dedicated internal/agent/ directory for Lobster routing, session storage and tool-call execution, separate from internal/im/, which holds the WuKongIM control-plane client. Those two concerns are not tangled together in the tree, which suggests the agent path can evolve without rewriting the messaging path.

Request flow: auth, authorisation, agent session, IM fan-out

The README spells out a five-step pipeline for each request. First, authenticate via token, cookie, or a DH-sealed WebSocket frame. Second, authorise with org-aware RBAC, per-channel ACLs, and agent-identity gating. Third, execute business logic, which may spawn or resume a Lobster agent session. Fourth, fan out by enqueuing an IM message through WuKongIM and triggering adapters when a channel needs an external bridge. Fifth, respond with a unified JSON envelope or WebSocket frame carrying tracing and metrics tags.

The third step is the interesting one. Spawning or resuming an agent session inside the request path means agent state has to live somewhere durable, and the README points at internal/agent/ for a session store. It does not document what happens when an agent session is mid-flight and the server restarts. That is a real gap for anyone planning to run this in production, because the answer determines whether a tool call can be lost silently.

The storage side is conventional: internal/repository/ holds SQL and cache repositories over MySQL and Redis, and migrations/ carries SQL schema migrations. The go.mod confirms the shape of that stack with go-sql-driver/mysql, go-redis/redis, gocraft/dbr, and rubenv/sql-migrate. Object storage is pluggable, with MinIO, Aliyun OSS and Qiniu SDKs all present as dependencies, which matches the README's claim that object-storage adapters ship in the box.

Building octo-server from source and running it with a config file

The README gives a four-command quickstart. Clone the repository, build the binary with the Go toolchain, then start it against a YAML config. The go.mod declares go 1.25, and the Dockerfile builds on golang:1.25, so a recent toolchain is required.

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 README states that the default dev config expects a local WuKongIM instance and a MySQL-compatible database. It points to configs/tsdd.yaml as the standalone-binary template, QUICKSTART.md for an end-to-end walkthrough, and BUILDING.md for cross-repo build notes. The README does not document what the server prints on a successful start, so there is no expected-output line to check against.

If you prefer containers, the README directs you to the official OOTB deployment repository, Mininglamp-OSS/octo-deployment, which is described as a one-command Docker Compose stack covering server, admin, web, matter, smart-summary, WuKongIM, MySQL, Redis, MinIO and nginx. The older docker/octo/ and docker/tsdd/ compose stacks that used to live in this repository have been retired. The Makefile reinforces this: run-dev and stop-dev now print a message pointing at octo-deployment and exit with status 1 rather than starting anything.

For image builds, the Makefile has a build target that runs docker build -t octo-server ., and deploy targets that tag and push to an Aliyun registry under the wukongim namespace. The Dockerfile builds a static binary with CGO_ENABLED=0 and embeds commit, commit date, version and tree state through -ldflags. It notes that git describe falls back to "dev" when no tags exist, which is what an OSS checkout without tags will produce.

The dev loop is split across repositories, and that costs you

The most concrete limitation is structural. To exercise octo-server end to end you need a WuKongIM instance and a MySQL-compatible database, plus Redis for the cache repositories. The README says the bundled dev config expects both. The compose stack that would have given you all of that in one command has been moved out of this repository, and the Makefile targets that used to start it now fail deliberately.

That is a defensible choice for the maintainers, who want a single source of truth for deployment. It is friction for you. A contributor fixing a bug in internal/im/ has to clone a second repository, run its setup script, and bring up nine services before the first request reaches their patched code. The README does not document a lighter path for IM-less testing, and the repository layout does not show a mock WuKongIM under test directories.

A second limitation is the pinned dependency on octo-lib. The go.mod requires github.com/Mininglamp-OSS/octo-lib at a pseudo-version dated 2026-08-11, not a tagged release. Pseudo-versions are immutable once fetched, which is good for reproducibility, but they also mean an upgrade of octo-lib requires a deliberate go get against a new commit rather than a version bump. If that module is not reachable through your module proxy, the build stops at go mod download, which is the first step the Dockerfile runs.

Third, the request pipeline includes agent-identity gating without saying how identities are provisioned or rotated. If you plan to run Lobster agents against external tools, that is the part of the documentation you will hit first and the README does not cover it.

How this differs from Mattermost or a plain self-hosted chat server

The obvious comparison is a self-hosted team chat server such as Mattermost. Both give you REST and WebSocket APIs, channels, groups, files and an admin surface, and both can be run on your own hardware. The difference is where the agent logic lives.

In a chat server, a bot is a client. It connects over the same API as a human, holds a token, and receives messages the way any other participant does. The server does not know or care that it is a bot. In octo-server, agents are woven into the request pipeline: the third step of the documented flow can spawn or resume a Lobster session, and internal/agent/ holds routing, a session store and tool-call execution. The server is aware that a participant is an agent and gates it accordingly.

That buys you tighter control over agent identity and session continuity, and it means agent scheduling is not an external service you have to build. It costs you the simplicity of a uniform client model. If your requirement is a chat server with a few webhook bots, the extra machinery here is weight you will carry without using. If your requirement is a workplace where agents hold sessions, call tools and act on channels, the alternative is building that orchestration layer yourself on top of a chat server, which is a substantially larger project than deploying this one.

Licence, maintenance and what an upgrade actually involves

octo-server is Apache-2.0, and the README states that every open-source cut ships as a self-contained product with one squash per release. The NOTICE file at the repository root is the place to check for attribution requirements that travel with redistribution. Apache-2.0 also includes an express patent grant and requires that modified files carry prominent notices of change. That is a general description of the licence, not advice about your situation; if you are redistributing a modified octo-server, read the LICENSE and NOTICE files in the release you take.

The release cadence is visible in the tags: v1.16.0 on 2026-08-24, v1.17.0 on 2026-08-31, v1.18.0 on 2026-09-07. The last push to the default branch was on 2026-09-10. Weekly cuts at that spacing mean the upgrade surface is live rather than frozen, and the RELEASING.md file at the root is where the maintainers describe their process.

The upgrade cost is dominated by two things. Database migrations live in migrations/ and are applied through rubenv/sql-migrate, so a version bump may include schema changes that need to run before the new binary starts. And the octo-lib pseudo-version in go.mod will move between releases, so pulling a new octo-server tag can also pull new shared-library behaviour. Neither is unusual, but both mean an upgrade is a build-and-migrate operation rather than a binary swap. The README does not document rollback, so plan your own.

Editorial conclusion

Adopt octo-server if you are building or extending the OCTO platform and can supply the surrounding pieces: a MySQL-compatible database, Redis, a WuKongIM instance, and the octo-lib module the go.mod pins by pseudo-version. Do not adopt it as a drop-in replacement for a plain self-hosted chat server, because the IM core sits outside this repository and the local compose stack has been retired. Before committing, verify two things: that the pinned octo-lib pseudo-version resolves in your module proxy, and that QUICKSTART.md's end-to-end path still matches the configs/tsdd.yaml keys in the release you pull.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Mininglamp-OSS/octo-server on GitHub
3. Project website
4. README
5. Releases