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 Android
> **Native Android client** for the OCTO messaging platform โ Kotlin / Java, talking to `octo-server` over REST + WebSocket.
`octo-android` is the official Android front-end for OCTO. It is a native
Kotlin / Java app (not a webview wrapper) that talks to
[`octo-server`](https://github.com/Mininglamp-OSS/octo-server) over REST +
WebSocket, and drives the same Lobster-agent conversation surface as
[`octo-web`](https://github.com/Mininglamp-OSS/octo-web).
## ๐ Why OCTO Android
- **Native, not a webview.** AndroidX-based, Material-themed, uses platform features (Foreground Service for message push, Scoped Storage for attachments, Jetpack Compose / XML views) rather than shipping a browser shell. First-class mobile UX for Lobster conversations.
- **Ships without secrets.** No `google-services.json`, no keystore, no Play Store listing bound to the upstream. You bring your own Firebase project, your own Bundle ID (`com.example.octo` placeholder โ `com.yourcompany.octo`), your own keystore. All baked-out via the `octo-release` pipeline before this repo is published.
- **Mirrors the web surface.** Same REST + WebSocket protocol as `octo-web`, same i18n resource keys (English ยท ็ฎไฝไธญๆ), same Lobster identity / streaming / typing indicators โ so feature work can land on both clients without a protocol fork.
## ๐ฅ Download
Download the latest APK from [**Releases**](https://github.com/Mininglamp-OSS/octo-android/releases), install it on your device, and enter your own `octo-server` address on the login screen.
> No build required โ just install and connect to your deployment.
## ๐ Quickstart
**โ ๏ธ Mandatory pre-flight** โ this fork will **not** build a distributable
APK until you swap three placeholder artefacts:
1. **Bundle ID / `applicationId`** โ see [`README-BUNDLE-ID.md`](README-BUNDLE-ID.md)
for the full rename checklist (`com.example.octo` โ your reverse-DNS).
2. **Firebase configuration** โ see [`firebase-template.md`](firebase-template.md)
for how to obtain and drop in your own `google-services.json`.
3. **Release keystore** โ see [`keystore-template.md`](keystore-template.md)
for how to generate a signing keystore and wire it into Gradle.
Once those are done, a dev debug build is straightforward:
```bash
git clone https://github.com/Mininglamp-OSS/octo-android.git
cd octo-android
# Open in Android Studio (Giraffe+) and let it sync, or from CLI:
./gradlew :app:assembleDebug
# Install on a connected device:
./gradlew :app:installDebug
```
By default the app points at `http://localhost:8080` for `octo-server`.
Edit `app/src/main/res/values/config.xml` (or the flavor-specific
equivalent) to aim at your own deployment.
## ๐ฆ Modules / Architecture
Top-level layout (typical OCTO Android tree):
| Path | Purpose |
|---|---|
| `app/` | Main application module โ activities, fragments, navigation graph |
| `app/src/main/java/.../ui/` | Screen surfaces: chat, channels, org, settings |
| `app/src/main/java/.../data/` | REST + WebSocket client, local cache, Room DAOs |
| `app/src/main/java/.../agent/` | Lobster-aware UI components (streaming, tool-call previews, agent identity) |
| `app/src/main/java/.../push/` | Firebase Messaging receiver + notification routing |
| `app/src/main/res/` | Layouts, drawables, XML configs, i18n (`values-en`, `values-zh-rCN`) |
| `wukong-sdk/` | WuKongIM Android client wrapper (real-time messaging transport) |
| `common/` | Shared utilities (crypto, time, JSON) |
| `buildSrc/` | Gradle convention plugins, dependency versions |
Runtime pillars:
1. **Auth** โ token / refresh-token stored in EncryptedSharedPreferences.
2. **Transport** โ OkHttp for REST + the WuKongIM Android SDK for the persistent WebSocket.
3. **Persistence** โ Room database for message cache and offline drafts; Scoped-Storage-safe attachment handling.
4. **Push** โ Firebase Cloud Messaging โ foreground service โ local notification channel.
5. **UI** โ single-Activity + fragments (or Compose screens depending on flavour), Material 3 theming, RTL-safe layouts.
## ๐ 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-android` owes its original scaffolding to:
- **[TangSengDaoDaoAndroid](https://github.com/TangSengDaoDao/TangSengDaoDaoAndroid)** โ our upstream, by the TangSengDaoDao team.
- **[WuKongIM](https://github.com/WuKongIM/WuKongIM)** โ the real-time messaging core that `octo-server` drives behind this client.
See [NOTICE](NOTICE) for the full attribution list and third-party component licenses.
---
Made with ๐ by OCTO Contributors ยท Mininglamp-OSS