# OCTO Web: the React and Electron client for the OCTO workplace

> Mininglamp-OSS/octo-web is the browser and PC front end for the OCTO messaging platform, built as one React and TypeScript codebase with dedicated UI for AI agent conversations. It needs a separate octo-server to do anything.

**Mininglamp-OSS/octo-web** — Web & desktop (Electron) client for the OCTO open workplace — one React + TypeScript codebase shipping browser and PC surfaces, with first-class AI agent UX.

- Repository: https://github.com/Mininglamp-OSS/octo-web
- Website: https://github.com/Mininglamp-OSS
- Stars: 1,183 · Forks: 181
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/mininglamp-oss-octo-web

## What octo-web actually is, and who it is for

octo-web is the front end of the OCTO workplace, a messaging platform whose repository matrix lists nine components. It is not a standalone chat product. It talks to octo-server over REST and WebSocket, and that server is where business orchestration and what the README calls "Lobster agent scheduling" live. If you do not run octo-server, the client has nothing to render.

The audience is narrower than the tagline suggests. You are a developer or platform team deploying the OCTO stack, or someone evaluating the client half of it before committing to the server. The README frames the product around "humans × AI agents", with Lobsters described as OpenClaw-powered digital doubles. That framing matters for the UI: the client ships dedicated surfaces for agent conversations rather than treating an agent as just another contact. The README lists streaming replies, a typing indicator, inline tool-call previews, read receipts, and identity chips that distinguish agent from human.

What it is not: a general-purpose chat widget you drop into an existing app, and not a library. It is an application, shipped as a browser bundle and an Electron package.

## One React tree, two shipped surfaces

The central design decision is that the browser build and the PC build come from the same src/ directory. The README is explicit that there are "no parallel React trees, no diverging UX", and that branching happens only at platform-capability boundaries. That is a real constraint, not marketing: every component has to work in a plain browser environment, so anything native has to be reached through an abstraction rather than called directly.

The Electron shell is described as intentionally thin. It hosts the same React app and forwards IPC for native capabilities: tray, notifications, file drop, and auto-update. The browser build runs with no Electron dependency at all. The practical consequence is that a feature which only makes sense on the desktop, such as auto-update, cannot leak into shared component code without breaking the web target.

The repository layout reflects this split. src/pages/ holds route-level views for chat, channels, org, and settings. src/components/ holds the shared UI kit: message bubbles, inputs, agent chips, streaming renderers. src/store/ holds client state for auth, channels, draft, and agent orchestration UI state. src/api/ is the REST and WebSocket client. electron/ holds the main and renderer bootstrap. The monorepo is managed with Turborepo and pnpm workspaces, and package.json shows the top-level scripts delegating through turbo run.

## Installing octo-web and pointing it at a server

The README quickstart is four commands. It assumes pnpm is available and that you already have an octo-server instance, because the default configuration expects one reachable at http://localhost:8080.

```bash
git clone https://github.com/Mininglamp-OSS/octo-web.git
cd octo-web
pnpm install
pnpm dev
```

After pnpm dev the browser build comes up. If nothing loads, the first thing to check is the server, not the client. To point the client elsewhere, the README says to copy .env.example to .env.local and edit the VITE_API_* values. Those are build-time Vite variables, so a change requires restarting the dev server.

The package.json in the repository also shows a Docker path. The Dockerfile builds with node:22.16.0-bookworm, installs pnpm@10 globally, runs pnpm install --frozen-lockfile and pnpm turbo run build --filter=@octo/web, then serves the result from nginx:alpine. The Makefile wraps this in two targets.

```bash
make build   # docker build -t octoweb .
make deploy  # tag and push to your-registry.example.com/octoweb:latest
```

The Makefile notes you should replace your-registry.example.com/octoweb with your own registry path before using deploy. Several VITE_ENTERPRISE_* and VITE_DOCS_* build arguments are declared in the Dockerfile, which suggests the image is meant to be parameterised per deployment rather than rebuilt from source each time.

For the desktop build, package.json exposes pnpm pc:dev to launch the Electron shell against the dev build and pnpm pc:package to produce a distributable bundle for macOS, Windows, or Linux. There are also platform-specific variants such as build-ele:mac and build-ele:linux-arm64. Note that the README's quickstart block uses pnpm dev, while package.json defines dev as a turbo run that filters out apps/extension; the two are consistent, but the README does not spell out the workspace layout.

## Bilingual UI is enforced, not aspirational

English and Simplified Chinese ship together, and the README states that i18n keys live in src/locales/ and are enforced in CI. That enforcement is visible in the repository: package.json defines i18n:scan, i18n:check, and i18n:baseline, all routed through scripts/i18n-scan.mjs. The presence of a baseline command implies the project tracks a known set of keys and fails when the set drifts.

This is a stronger position than most projects take. Translation drift is usually caught by review, which means it is caught late. Here it is a build gate. The cost is that adding a user-facing string without adding its keys will break CI, which is a friction point for contributors who are used to hardcoding English text and moving on. If you fork octo-web and only need one language, you will be fighting that gate rather than benefiting from it.

The same pattern appears in CSS. package.json defines lint:css and lint:css:ci, and both chain into lint:wkmodal, which runs scripts/check-wkmodal-semi-overrides.mjs. Stylelint configuration exists in two files, stylelint.config.mjs and stylelint.ci.config.mjs, so the CI ruleset is deliberately stricter than the local one.

## The backend dependency is the real limitation

The most consequential thing about octo-web is what it cannot do alone. Every feature that matters, messaging, channels, the org view, agent orchestration, depends on octo-server. The README's quickstart assumes a local server at http://localhost:8080 and does not describe how to obtain or run one. You are expected to go to the octo-server repository.

That makes octo-web the wrong tool for anyone who wants a chat interface without the OCTO platform behind it. The upstream attribution is worth reading here: the README credits TangSengDaoDaoWeb as the original scaffolding and WuKongIM as the real-time messaging core that octo-server drives behind this client. So the client's lineage is a web client for a WuKongIM-based messaging backend. If your requirement is a generic IM front end, evaluating the upstream projects directly may be more informative than evaluating this fork.

A second limitation is documentation depth. The README covers the quickstart, the module layout, and the build targets. It does not document rollback, migration between versions, or what happens to client state when the server is upgraded. The release history shows frequent cuts, roughly weekly through August and early September 2026, with v1.16.0 on 2026-09-07. That cadence is a maintenance signal, but the README gives no compatibility matrix, so you cannot tell from the documentation alone whether a given client version requires a minimum server version. Verify that against octo-server's own release notes before upgrading either side.

## How it compares to a native client or building your own

The OCTO matrix offers two other client paths: octo-android in Kotlin and Java, and octo-ios in Swift and Objective-C. Those are native codebases with their own UI layers, so they will feel correct on their platforms in ways a web view does not, particularly around input, scrolling, and background behaviour. The trade-off is that they are separate codebases. A change to how agent conversations render has to be made three times.

octo-web takes the opposite position: one React tree, two surfaces, with the PC build wrapped in a thin Electron shell. If your team writes TypeScript and you care about shipping the same conversation UI to browser and desktop without maintaining two implementations, that is the argument for this repository. If your users are primarily on phones, the native clients are the ones the matrix points at, and octo-web is not the answer.

The third option is writing your own client against octo-server. The README says the client talks to the server over REST and WebSocket, so the interface exists. But you would be rebuilding the agent-specific UI that this repository already ships: streaming replies, tool-call previews, identity chips, read receipts. That is the part of octo-web with the most project-specific work in it.

## Licence and the cost of staying current

octo-web is Apache-2.0, and the repository carries both a LICENSE and a NOTICE file. The README directs readers to NOTICE for third-party attributions and component licences. For a client that credits an upstream project and a messaging core, the NOTICE file is the document to read before redistributing a build, because Apache-2.0 requires you to preserve attribution notices. This is not legal advice; if you plan to ship a modified octo-web commercially, have counsel review NOTICE and the upstream licences.

The upgrade cost is dominated by the release cadence. Releases v1.14.0 through v1.16.0 landed on 2026-08-24, 2026-08-31, and 2026-09-07, and the last push to the repository was on 2026-09-10. That is a weekly-ish rhythm, which means pinning to a version and jumping several releases at once is a realistic strategy, but the README does not describe a migration process. The i18n baseline mechanism is the one piece of upgrade tooling that is documented, through pnpm i18n:baseline, and it exists to absorb key drift rather than to migrate behaviour.

Contributors should also read DEVELOPMENT.md and RELEASING.md, both present at the repository root, along with AGENTS.md and CLAUDE.md, which suggest the project expects AI-assisted contributions and has written down its conventions for them.

## Conclusion

Adopt octo-web if you are standing up an OCTO deployment and want the browser surface plus an Electron PC build from one React tree; skip it if you only want a chat UI and have no octo-server, because the client has nothing to talk to. Before committing, verify that your octo-server exposes REST and WebSocket on the address you configure through VITE_API_*, and run pnpm i18n:check in CI so English and Simplified Chinese keys stay in sync.

## FAQ

### Does octo-web need a backend server to run?

Yes. The README states that octo-web talks to octo-server over REST and WebSocket, and the default configuration expects a server reachable at http://localhost:8080. Without octo-server running, the client has nothing to display.

### How do I point octo-web at my own OCTO server?

The README says to copy .env.example to .env.local and edit the VITE_API_* values. Because these are Vite variables, the dev server has to be restarted for the change to take effect.

### Can octo-web be built as a desktop application?

Yes. The same React codebase ships as an Electron-packaged PC client, and package.json provides pnpm pc:dev to launch the Electron shell against the dev build and pnpm pc:package to produce a distributable bundle for macOS, Windows, or Linux.

### What licence does octo-web use?

It is Apache-2.0. The repository includes both a LICENSE file and a NOTICE file, and the README points to NOTICE for third-party attributions and component licences.

## Sources

- [License: Apache-2.0](https://github.com/Mininglamp-OSS/octo-web/blob/main/LICENSE)
- [Mininglamp-OSS/octo-web on GitHub](https://github.com/Mininglamp-OSS/octo-web)
- [Project website](https://github.com/Mininglamp-OSS)
- [README](https://github.com/Mininglamp-OSS/octo-web/blob/main/README.md)
- [Releases](https://github.com/Mininglamp-OSS/octo-web/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mininglamp-oss-octo-web