OCTO โ the open workplace built for humans ร AI agents.
Let Lobsters (OpenClaw-powered digital doubles) do the thinking and doing. You focus on taste.
๐ OCTO Home ยท
๐ Quickstart ยท
๐ฆ Ecosystem ยท
๐ค Contributing
---
> ๐ **Read in**: **English** ยท [็ฎไฝไธญๆ](README.zh.md)
# OCTO Server
> **The Go backend** at the centre of OCTO โ REST + WebSocket APIs, Lobster agent orchestration, and the control plane for WuKongIM.
`octo-server` is the heart of the OCTO platform. It exposes REST +
WebSocket APIs consumed by
[`octo-web`](https://github.com/Mininglamp-OSS/octo-web) and
[`octo-admin`](https://github.com/Mininglamp-OSS/octo-admin), orchestrates
business logic and Lobster (AI agent) scheduling, and drives the
[`WuKongIM`](https://github.com/WuKongIM/WuKongIM) IM core for real-time
messaging.
## ๐ Why OCTO Server
- **One anchor for the whole platform.** Clients, adapters, matter, summary, and admin all meet at `octo-server`. Deploy and scale one backend; everything else speaks to it.
- **Lobster-orchestration first class.** Routing, session, and tool-call execution for OpenClaw-powered digital doubles are built into the server, not bolted on. Agents are treated as first-class conversation participants.
- **Pluggable storage & IM.** MySQL-compatible SQL migrations and object-storage adapters ship in the box; WuKongIM is driven over a thin control-plane boundary so the IM core remains swappable.
## ๐ Quickstart
```bash
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 default dev config expects a local WuKongIM instance and a
MySQL-compatible database. See the bundled `configs/tsdd.yaml`
template for the standalone-binary path, [`QUICKSTART.md`](./QUICKSTART.md) for an
end-to-end walkthrough, and [`BUILDING.md`](./BUILDING.md) for
cross-repo build notes.
For a one-command Docker Compose stack (server + admin + web + matter
+ smart-summary + WuKongIM + MySQL + Redis + MinIO + nginx), use the
**official OOTB deployment** at
[`Mininglamp-OSS/octo-deployment`](https://github.com/Mininglamp-OSS/octo-deployment).
The older `docker/octo/` and `docker/tsdd/` compose stacks that used
to live in this repo have been retired in favour of that single
source of truth.
## ๐ฆ Modules / Architecture
High-level layout:
| Path | Purpose |
|---|---|
| `cmd/` | Service entry points (`octo-server`, subcommands) |
| `internal/api/` | REST + WebSocket handlers โ conversation, user, group, file, org, webhook |
| `internal/service/` | Business logic โ access control, Lobster orchestration, IM fan-out |
| `internal/repository/` | SQL + cache repositories (MySQL, Redis) |
| `internal/im/` | Control-plane client for WuKongIM (channel / message / presence) |
| `internal/agent/` | Lobster routing, session store, tool-call execution |
| `internal/adapter/` | Adapter registration + dispatch surfaces |
| `configs/` | YAML config schema + dev / prod examples |
| `migrations/` | SQL schema migrations |
| `docs/` | Architecture notes, API reference, diagrams |
What the server does each request:
1. **Authenticate** โ token / cookie / DH-sealed WebSocket frame.
2. **Authorise** โ org-aware RBAC, per-channel ACL, agent-identity gating.
3. **Execute** โ run business logic, possibly spawning / resuming a Lobster agent session.
4. **Fan out** โ enqueue IM message via WuKongIM, trigger adapters if the channel requires an external bridge.
5. **Respond** โ unified JSON envelope (or WebSocket frame) with tracing + metrics tags.
## ๐ OCTO Ecosystem
```mermaid
graph TD
subgraph Clients[Clients]
Web[octo-web
Web / PC]
Android[octo-android
Android]
iOS[octo-ios
iOS]
end
subgraph Core[Core Services]
Server[octo-server
Backend API]
Matter[octo-matter
Task / Todo]
Summary[octo-smart-summary
AI Summary]
Admin[octo-admin
Admin Console]
end
subgraph Shared[Shared Libraries & Integrations]
Lib[octo-lib
Core Go Library]
Adapters[octo-adapters
Third-party Adapters]
end
Web --> Server
Android --> Server
iOS --> Server
Admin --> Server
Server --> Matter
Server --> Summary
Server --> Adapters
Server -.uses.-> Lib
Matter -.uses.-> Lib
Adapters -.uses.-> Lib
```
| Repository | Language | Role |
|---|---|---|
| [`octo-server`](https://github.com/Mininglamp-OSS/octo-server) | Go | Backend API ยท business orchestration ยท Lobster agent scheduling |
| [`octo-matter`](https://github.com/Mininglamp-OSS/octo-matter) | Go | Task / Todo / Matter micro-service |
| [`octo-smart-summary`](https://github.com/Mininglamp-OSS/octo-smart-summary) | Go | LLM-powered conversation summarisation |
| [`octo-web`](https://github.com/Mininglamp-OSS/octo-web) | TypeScript / React | Web & PC (Electron) client |
| [`octo-android`](https://github.com/Mininglamp-OSS/octo-android) | Kotlin / Java | Native Android client |
| [`octo-ios`](https://github.com/Mininglamp-OSS/octo-ios) | Swift / Objective-C | Native iOS client |
| [`octo-admin`](https://github.com/Mininglamp-OSS/octo-admin) | TypeScript / React | Admin console (tenant / org / user / channel management) |
| [`octo-lib`](https://github.com/Mininglamp-OSS/octo-lib) | Go | Shared core library (protocol, crypto, storage, HTTP) |
| [`octo-adapters`](https://github.com/Mininglamp-OSS/octo-adapters) | TypeScript / Python | Third-party integrations (IM bridges, AI channels) |
## ๐งญ Philosophy
OCTO ships under three shared principles that apply to every repository in this matrix:
1. **Local-first.** Anything that can run on the user's own box โ chats, embeddings, agents โ should. Your data stays yours; cloud is a choice, not a requirement.
2. **Humans judge, AI thinks and acts.** Humans focus on *taste* (what matters, what's right, what to ship). Lobster agents โ OpenClaw-powered digital doubles โ carry the *thinking* and *execution* load.
3. **Release-as-product.** Every open-source cut is shipped as a self-contained product, not a code dump: one squash per release, Apache 2.0, no internal baggage, reproducible from this repo alone.
## ๐ค Contributing
We love pull requests! Before you open one, please read:
- [CONTRIBUTING.md](CONTRIBUTING.md) โ workflow, branch model, commit style
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) โ community expectations
For security issues please follow [SECURITY.md](SECURITY.md) instead of the public tracker.
## ๐ License
Apache License 2.0 โ see [LICENSE](LICENSE) for the full text and [NOTICE](NOTICE) for third-party attributions.
## ๐ Acknowledgments
`octo-server` is a derivative work of:
- **[TangSengDaoDaoServer](https://github.com/TangSengDaoDao/TangSengDaoDaoServer)** โ our upstream, by the TangSengDaoDao team.
- **[WuKongIM](https://github.com/WuKongIM/WuKongIM)** โ the real-time messaging core we drive.
See [NOTICE](NOTICE) for the exhaustive Go module license inventory and third-party attribution block.
---
Made with ๐ by OCTO Contributors ยท Mininglamp-OSS