[RFC / Design Discussion]: Native iOS Companion Client for Remote OmniRoute Instances

[Primuez]

Context and Motivation

Following up on the discussion in #18744:
We completely agree with the architectural assessment regarding on-device execution — embedding a Node.js runtime and better-sqlite3 native addons within the sandboxed iOS environment is technically prohibitive and outside the core mission of OmniRoute (which ships Node.js server, Docker, and Electron desktop).

The practical and standard production pattern for mobile usage is running OmniRoute remotely (on a VPS, home server, or Mac via Docker) and reaching it securely via Tailscale, WireGuard, or reverse proxy.

However, managing routes, monitoring real-time quotas, and leveraging OmniRoute from an iPhone/iPad currently relies on Mobile Safari. While functional, it leaves significant mobile-first capabilities on the table.

This RFC proposes designing a lightweight, native Swift / SwiftUI Companion Client specifically built to connect to and control remote OmniRoute instances.

---

Proposed Architecture and Features

1. Remote Instance Management

• Connection Profiles: Multi-instance support (e.g. Home Server, VPS, Work Cloud) via URL + Admin API Key / Bearer token.
• Network Support: Seamless connectivity over Tailscale MagicDNS, WireGuard VPN, local LAN, or public HTTPS.
• Heartbeat and Latency Check: Continuous background status indicators of remote gateway uptime and active upstream models.

2. Real-Time Telemetry and Quota Monitoring

• Live Stream Tracking: Monitor active inference requests, token throughput, and token compression ratios via OmniRoute's existing SSE streams.
• Dynamic Island / Live Activities: Glanceable token generation progress and streaming status during active prompt executions.
• Quota Dashboards: Native mobile charts for provider token limits, spend caps, and failover trigger logs.

3. Remote Policy and Model Control

• Quick-toggle upstream providers and custom model fallbacks (Anthropic, OpenAI, Antigravity, OpenRouter, Ollama, etc.).
• Adjust compression settings, reasoning routing effort modes (targetEffort, etc.), and retry policies directly from mobile.

4. Native iOS Ecosystem Integrations

• App Intents and Siri Shortcuts: Native action blocks (e.g., "Route Prompt through OmniRoute", "Get Remaining Provider Quota", "Switch OmniRoute Fallback Profile") allowing mobile coding agents (Blink Shell, a-Shell, Shortcuts workflows) to integrate directly.
• Widgets: Home Screen and Lock Screen widgets for daily token savings and upstream provider health.
• Keychain Security: Secure enclave storage for instance authentication tokens and API keys.

---

Non-Goals (Scope Discipline)

• No Embedded Engine: No local Node.js runtime, no local SQLite compilation, and no on-device model routing.
• Zero Server Overhead: The client strictly uses existing REST and SSE endpoints already exposed by the OmniRoute server.

---

Questions and Guidance from Maintainers

1. Repository Structure: Would maintainers prefer this client structured within this monorepo (e.g., clients/ios/ or mobile/) or as an independent repository under the cheaper-inference organization?
2. API and Auth Stability: Are the current admin / metrics REST endpoints and SSE telemetry streams considered stable for third-party client consumption, or is an explicit Client API contract preferred?
3. Prototype Collaboration: If the community prepares an initial SwiftUI MVP (Connection + Live Metrics + Siri Shortcuts), would the team be open to reviewing the PR/spec?

We would love to hear feedback and design constraints from the maintainers before writing code.

[Primuez]

Additional context on developer economics & deployment cost:

A major motivating factor for exploring mobile-first access is infrastructure cost. With cloud VPS rates frequently doubling on renewal (e.g. standard KVM tiers climbing past $15–$20/mo), keeping a dedicated 24/7 cloud instance running solely to proxy mobile LLM traffic is becoming prohibitive for individual developers and indie hackers.

This makes native iOS remote support even more compelling for cost-conscious developers:

1. Zero-cost home servers: Seamless connection to a local Mac or home machine running Docker over Tailscale / WireGuard when on mobile, avoiding monthly VPS hosting bills entirely.
2. Ephemeral / on-demand handling: Graceful handling when the home host is asleep or reconnecting.
3. Future-proofing: Keeping the long-term backlog open for an ultra-lightweight runtime (e.g., WASM or embedded core) if/when sandbox-compatible engines make local mobile execution feasible without a server.

[diegosouzapw]

@Primuez Agreed on the premise: OmniRoute keeps running on a server, and the phone reaches it over Tailscale, WireGuard or HTTPS.

A native Swift client won't live in this repo, though. It would be a separate app with its own signing, App Store review and release cycle, and I can't maintain that next to the server. It can be built entirely outside the repo, since everything you list (instances, quotas, usage, live requests) is already served over HTTP by the same /api/* routes the dashboard uses. If you or anyone starts one, post it in Show and tell and I'll point people to it.