Odysseus mobile companion app: React Native, private pairing, and App Store path

[jongan69]

Why this matters

The current ChatGPT mobile app and Codex-style workflows prove there is real demand for being able to work from a phone while the actual compute and project state live elsewhere. The gap is that those workflows depend on a hosted subscription and a third-party app in the middle.

Odysseus is already aimed at the opposite model: local-first, privacy-first, user-owned orchestration. A mobile companion should extend that: the phone is the control surface, while the user's own Odysseus server, models, tools, and workspace remain the source of truth.

Current status

This is no longer just a hypothetical idea. The mobile companion work is already on a native iOS / App Store-track path:

• Public TestFlight link: https://testflight.apple.com/join/hdnWUB4X
• A separate Expo / React Native companion app exists outside the core Odysseus repo.
• It has been brought up as a custom native iOS dev client on a real iPhone, not just Expo Go or a web mock.
• QR-first pairing is working against the Odysseus companion contract.
• The app validates GET /api/companion/manifest before accepting pairing state.
• Local-network access and retry behavior have already been hardened enough for real-device testing.
• Per-session chat state and background continuity are active requirements, so switching tabs/apps should not blank an in-flight session.

So when I say we are basically already in the App Store, I mean this is at the native-app/distribution stage, not the “maybe someday we build a wrapper” stage. The next step is to make the TestFlight/App Store packaging and review story line up with the backend contract and privacy posture.

Backend contract already forming

The companion/backend slice in #3400 gives a clean foundation without adding mobile UI directly to the main repo:

• POST /api/companion/pair mints a private pairing token from an admin session.
• The QR payload gives the mobile client the token and private reachability details.
• GET /api/companion/manifest advertises supported features and required scopes.
• Mobile clients can list/create owner-scoped sessions and stream chat through /api/chat_stream.
• Signed companion commands use a registered Ed25519 device key plus nonce replay protection.
• Raw shell remains disabled; command authority is intentionally scoped and reviewable.

That is the right separation: Odysseus core exposes a stable private server contract, and the mobile app consumes it as a separate client.

Remote connection strategy

The simplest recommended remote path should be a private HTTPS transport, not trycloudflare Quick Tunnels.

trycloudflare is useful for quick browser demos, but it is a poor fit for the companion app because Odysseus chat uses Server-Sent Events (/api/chat_stream), and Cloudflare's Quick Tunnel docs currently list SSE as unsupported. Quick Tunnels also use random temporary *.trycloudflare.com URLs, so a pairing QR can become stale as soon as the tunnel process restarts.

Recommended order:

1. Tailscale Serve for the easiest private setup: keep Odysseus on localhost, expose it to the user's tailnet over HTTPS, set COMPANION_BASE_URL to the https://<device>.<tailnet>.ts.net URL, then mint a fresh pairing QR.
2. WireGuard or another private VPN for users who already have that infrastructure.
3. Named Cloudflare Tunnel + Cloudflare Access for users who want a stable custom domain and identity gate. This should be a configured tunnel, not trycloudflare.

For any non-LAN transport, the important backend rule is: set COMPANION_BASE_URL before minting the pairing token so the QR advertises the real remote origin instead of a LAN-only host/port.

This probably deserves docs and a setup checklist, but not a separate product direction from the mobile companion work.

Tailscale proof from the TestFlight build

These screenshots show the mobile companion being used with Tailscale VPN as the private remote transport. The phone does not need to be on the same LAN as the Odysseus server; it can reach the user's private Odysseus origin through the tailnet while keeping the server off the public internet.

The visible Chat resume failed: 404 is useful follow-up evidence too: remote reachability is working well enough for the mobile app to load and interact with the agent, but stale or expired detached-stream resume should degrade more cleanly on mobile. That should be handled as a resume-state UX/API edge case rather than treated as a VPN/tunnel failure.

What the mobile app should become

The first useful version should focus on daily remote control, not every desktop feature:

1. Pair securely with an owner-controlled Odysseus server over LAN, Tailscale, WireGuard, or a private authenticated HTTPS proxy.
2. Show available models/sessions from the user's server.
3. Start and resume chat/agent turns from the phone.
4. Keep session state durable across app switches, tab switches, and backgrounding.
5. Expose safe signed commands only where the backend manifest says they are available.
6. Provide a local “forget device” flow that clears token/key material.
7. Preserve the privacy-first story clearly enough for TestFlight/App Store review.

Longer-term opportunity

The larger unlock is mobile access to long-running autonomous work. I opened a separate discussion for a first-class Pursue Goal mode here: #3585.

If Odysseus has a durable goal runner and the mobile app can start/resume/monitor it, the phone becomes more than a chat surface. It becomes a way to kick off meaningful local work, check progress, approve human-in-the-loop decisions, and come back later without babysitting the desktop.

That could be a real differentiator: local model privacy, owner-controlled tools, and mobile-first control of long-running work.

Open questions

• Should the mobile app live as a separate official repo, or under this org as a sibling project?
• What private transport should be documented first: LAN, Tailscale, WireGuard, or authenticated HTTPS proxy?
• How much of signed workspace control should be visible in v1 versus hidden behind an advanced/developer mode?
• What exact App Store privacy wording do we want for local-network access, camera QR scanning, and self-hosted server credentials?
• Should Pursue Goal support be exposed in the mobile app as soon as the backend runner exists, or wait until the desktop UX proves it first?

Suggested next step

Keep #3400 focused on the backend/mobile contract. In parallel, treat the Expo / React Native app as the companion client track and work toward a TestFlight-ready build that demonstrates:

• scan QR,
• validate manifest,
• list/create sessions,
• stream chat/agent turns,
• resume an in-flight turn,
• preserve session state after app switches,
• and safely forget local credentials.

[jongan69]

So far Im working entirely in one pr bc I figure I can just run and test in there #3400

Not professional, my apologies, I just really wanted to spearhead such a workflow, been wanting to for months and this project gives the idea actual legs, can scrap it if poorly executed but Ill keep my fork as updated and functional as possible without interfering with the current tickets at bay

[jongan69]

I'm looking at #3244 now, just saw it

[jongan69]

App Store review surfaced a concrete blocker for the iOS companion that I would like guidance on.

Apple rejected Odysseus Companion under Guideline 1.5 because the Support URL in App Store Connect currently points to:
https://github.com/jongan69/odysseus-expo/blob/main/SUPPORT.md

Reviewer feedback was that this does not point to a proper public support website, and that a Support URL should not require a user to log in or create an account on a third-party service for non-account-related issues.

This seems less like a code problem and more like a product/release expectation problem for a privacy-first self-hosted app.

Questions for the community:

• What support URL pattern would you expect for a project like this?
• Is a simple public support page with contact info, FAQ, setup help, and troubleshooting enough?
• Would GitHub Pages be acceptable here, or should this live on a project-owned site/domain from day one?
• If you have shipped an App Store app with a self-hosted or open-source backend, what support/disclosure setup actually passed review?

My current lean is:

1. move support off the repo blob URL
2. publish a public support page with an email/contact path, pairing/setup help, and basic privacy notes
3. keep GitHub/docs/community links as secondary support, not the canonical Support URL

Interested in what people think is the minimal acceptable version versus the long-term right answer.

[jongan69]

Scope/alignment note with #3163: I do not see this thread itself as a Stabilization v1 candidate.

The stabilization lane should stay on narrow backend/trust-boundary/docs/test work like #3400. This discussion is the separate companion-client/TestFlight/App Store track that should consume that contract once it lands, not widen the core repo scope during stabilization.

[jongan69]

Here is the react native mobile app repo