OCTO iOS: the native client for an open workplace of humans and agents

A native client for a nine-repo workplace

OCTO describes itself as the open workplace built for humans and AI agents, with Lobsters, OpenClaw-powered digital doubles, doing the thinking and the doing while the human focuses on taste. Whatever one makes of the marketing framing, the substrate is concrete: a self-hostable enterprise messaging platform across nine repositories, of which this one is the official iOS front-end.

The client is native in the specific sense the README insists on: Swift and Objective-C, not a webview wrapper. It talks to the octo-server backend over REST and WebSocket, and it drives the same Lobster-agent conversation surface as the web and Android clients, which means agent conversations are a first-class mobile experience here rather than a desktop feature squeezed onto a phone.

The distinction matters for an agent-centric messenger. Streaming responses, typing indicators and tool-call previews are exactly the interface elements that suffer in browser-shell apps, and pushing them through UIKit and SwiftUI with native push behind them is the difference between an app people use and one they tolerate.

Ships without secrets, on purpose

The most deliberate thing in this repository is what is absent. No GoogleService-Info.plist, no signing certificates, no provisioning profiles bound to the upstream team: everything identifying is stripped by the release pipeline before publication, and what arrives is a template you complete with your own Apple Developer team, your own bundle identifier replacing the documented placeholder, your own Firebase project and your own certificates.

The README frames this as a mandatory pre-flight of four artefacts, and it is not overstated: the fork will not build a signed or distributable IPA until the bundle identifier is renamed across the project file, entitlements and every extension target, the Firebase configuration is dropped in, provisioning is bound to your certificates, and the Universal Links association file is hosted on your domain so deep links resolve.

This is the correct hygiene for open-sourcing an enterprise client. The alternative, shipping working credentials or team-bound profiles, is how repositories leak signing identity, and the checklist documents that repeatedly. The cost is honest: this is a build-your-own client for operators standing up their own OCTO deployment, not an app store download, and the repository never pretends otherwise.

Build and configuration

With signing configured, the workspace path is conventional:

git clone https://github.com/Mininglamp-OSS/octo-ios.git
cd octo-ios

pod install


open OCTO.xcworkspace   # or OCTO.xcodeproj

CocoaPods is optional, with Swift Package Manager handled by Xcode on open. From the command line, after signing is configured, a development build is one invocation:

xcodebuild -workspace OCTO.xcworkspace \
    -scheme OCTO \
    -configuration Debug \
    -destination 'generic/platform=iOS Simulator' \
    build

By default the app points at a local octo-server on port 8080, and the configuration file in the source tree is the documented place to aim the client at your own deployment. There is nothing exotic in the toolchain, which is itself information: the interesting complexity in this project lives in the extension targets and the agent surface, not in the build system.

The architecture, module by module

The layout table reads like a map of priorities. The main target carries view controllers and SwiftUI views. A UI layer holds the screen surfaces: chat, channels, organization, settings. A Data layer contains the REST and WebSocket client, local cache and the local persistence models, per flavour. An Agent layer holds the Lobster-aware components: streaming, tool-call previews, agent identity, the parts that make agent conversations legible on a phone.

Platform integration is where the native claim is cashed out. A Push module handles APNS registration, routing and a notification-service extension. A Share extension forwards content into OCTO from the share sheet. The notification extension is rich and encryption-aware, decrypting payload content before display. And a WuKongIM client wrapper provides the persistent WebSocket transport beneath the REST calls.

The runtime pillars close the picture: tokens and refresh tokens stored in the Keychain; URLSession for REST with the SDK for the socket; message cache and offline drafts in the local store, with attachments in the container; push flowing from the APNS token through the server with optional Firebase fan-out; and a UIKit navigation skeleton with SwiftUI screens where they pay off, Dynamic Type and Dark Mode supported by default. Localization ships in English and Simplified Chinese, matching the server's resource keys.

The ecosystem contract, kept in sync

The ecosystem diagram in this README is a shared snippet, marked to stay identical across all nine repositories, which is a small governance detail that prevents the classic drift where each client documents a different architecture. The matrix: a Go backend handling the API, business orchestration and Lobster agent scheduling; a Go task and todo micro-service; a Go LLM-powered conversation summarisation service; a TypeScript and React web client that also ships as a desktop build; native Android and iOS clients; a core Go library; third-party adapters; and an admin console.

For an adopter, the load-bearing property is protocol parity: the same REST and WebSocket surface, the same internationalization keys, the same Lobster identity, streaming and typing semantics across all three clients, so a feature lands everywhere without a protocol fork. The iOS repository's own claim to correctness is that it mirrors the web surface rather than inventing its own dialect.

That parity is also the adoption cost's justification. Standing up OCTO means standing up the server and at least one client, and the payoff for doing it is a workplace where the agent, not just the human, is a first-class participant in every channel.

Who builds with this, licence, and the neighbours

The audience is specific: organizations self-hosting OCTO who need an iOS client they can sign, brand and extend as their own, and iOS developers contributing to an agent-native messenger whose architecture table they can read in one screen. The licence is Apache-2.0 with a notice file, bilingual contribution and conduct documents round out the community scaffolding, and a secrets-scanning configuration sits in the tree, consistent with the strip-everything release posture.

The limits follow from the design. There are no published releases, so adoption means pinning a commit of a moving client. The pre-flight checklist is non-negotiable, which filters out anyone without an Apple Developer account and a backend to point at. And the client inherits whatever maturity the wider OCTO platform has reached, this review covers the repository, not a running deployment.

The neighbours frame the choice. Matrix-based clients in the Element lineage offer a mature federated protocol with a decade of hardening and no agent-native assumptions, the conservative choice. OCTO's bet is the opposite direction: a younger, self-hosted stack designed around AI-agent colleagues from the start, with Lobster scheduling in the server and agent-aware UI in every client. Teams choosing between them are really choosing whether the agent is a plugin to their messaging or the reason for it.

Editorial conclusion

octo-ios fits organizations already committed to self-hosting OCTO who need a native, rebrandable iOS client with real push, share and notification-extension integration, and iOS developers who want to work on an agent-first messenger with a readable architecture. It does not fit anyone expecting an app-store install, since the repository ships without signing material and requires the documented pre-flight, or teams without their own octo-server deployment to talk to. Verify first: the four pre-flight artefacts against your Apple team's setup, the bundle-identifier checklist across every extension target, and the maturity of the server release you will point the client at. The licence is Apache-2.0, and the last push was on 2026-09-17.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Mininglamp-OSS/octo-ios on GitHub
4. README