https://github.com/mininglamp-oss/octo-server

🐙 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.
https://github.com/mininglamp-oss/octo-server

ai-agents apache2 chat collaboration digital-workplace go golang im instant-messaging lobster openclaw rest-api self-hosted websocket wukongim

Last synced: 1 day ago
JSON representation

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

Host: GitHub
URL: https://github.com/mininglamp-oss/octo-server
Owner: Mininglamp-OSS
License: apache-2.0
Created: 2026-05-11T11:28:46.000Z (11 days ago)
Default Branch: main
Last Pushed: 2026-05-20T09:08:14.000Z (2 days ago)
Last Synced: 2026-05-20T09:56:55.134Z (2 days ago)
Topics: ai-agents, apache2, chat, collaboration, digital-workplace, go, golang, im, instant-messaging, lobster, openclaw, rest-api, self-hosted, websocket, wukongim
Language: Go
Homepage: https://github.com/Mininglamp-OSS
Size: 153 MB
Stars: 16
Watchers: 0
Forks: 7
Open Issues: 25
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Roadmap: docs/roadmap.md
- Notice: NOTICE

Awesome Lists containing this project

README

          


  

  





  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}

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/mininglamp-oss/octo-server

Awesome Lists containing this project

README