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 · 简体中文

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 and octo-admin, orchestrates business logic and Lobster (AI agent) scheduling, and drives the 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

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 for an end-to-end walkthrough, and BUILDING.md for cross-repo build notes. The WuKongIM callback listener (grpcAddr, default port 6979) and its TS_GRPC_AUTH_TOKEN / TS_GRPC_AUTH_REQUIRED settings are described in docs/webhook-grpc.md; TS_GRPC_AUTH_REQUIRED=true without a token makes the server refuse to start.

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. 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

graph TD
  subgraph Clients[Clients]
    Web[octo-web<br/>Web / PC]
    Android[octo-android<br/>Android]
    iOS[octo-ios<br/>iOS]
  end
subgraph Core[Core Services]
    Server[octo-server<br/>Backend API]
    Matter[octo-matter<br/>Task / Todo]
    Summary[octo-smart-summary<br/>AI Summary]
    Admin[octo-admin<br/>Admin Console]
  end
subgraph Shared[Shared Libraries & Integrations]
    Lib[octo-lib<br/>Core Go Library]
    Adapters[octo-adapters<br/>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 | Go | Backend API · business orchestration · Lobster agent scheduling | | octo-matter | Go | Task / Todo / Matter micro-service | | octo-smart-summary | Go | LLM-powered conversation summarisation | | octo-web | TypeScript / React | Web & PC (Electron) client | | octo-android | Kotlin / Java | Native Android client | | octo-ios | Swift / Objective-C | Native iOS client | | octo-admin | TypeScript / React | Admin console (tenant / org / user / channel management) | | octo-lib | Go | Shared core library (protocol, crypto, storage, HTTP) | | 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 — workflow, branch model, commit style
• CODE_OF_CONDUCT.md — community expectations

📄 License

Apache License 2.0 — see LICENSE for the full text and NOTICE for third-party attributions.

🙏 Acknowledgments

octo-server is a derivative work of:

• TangSengDaoDaoServer — our upstream, by the TangSengDaoDao team.
• WuKongIM — the real-time messaging core we drive.

_{Made with 🐙 by OCTO Contributors · Mininglamp-OSS}