Skip to content

ANDROID_APK.md

Latest commit

 

History

History
108 lines (77 loc) · 2.89 KB

ANDROID_APK.md

File metadata and controls

108 lines (77 loc) · 2.89 KB

CodexU Android APK

This project includes a Capacitor Android shell for personal sideload use on Samsung S23 Ultra.

Scope

  • APK bundles the Vue UI locally.
  • The app connects to a remote codex_xremote server with a mobile auth token.
  • Turn-complete notifications work in the foreground and while the app process remains alive in the background.
  • Closed-app push notifications are intentionally out of scope for v1.

Current Android targets

  • applicationId: com.opencode.codexxremote
  • appName: CodexU Mobile
  • minSdkVersion: 29
  • targetSdkVersion: 34
  • compileSdkVersion: 34

Prerequisites

  1. Node.js 18+
  2. Android Studio
  3. JDK 17 preferred

Gradle/Android builds will fail on Java 8. If java -version shows 1.8, switch to JDK 17 before building the APK.

Install

cd C:\Users\Administrator\Desktop\opencode\codex_xremote\upstream-source
npm install

Web build

npm run build

Sync Capacitor assets into Android

npm run cap:sync

Open Android Studio project

npm run cap:open

You can also build from the terminal:

cd C:\Users\Administrator\Desktop\opencode\codex_xremote\upstream-source\android
.\gradlew.bat assembleDebug

First-run mobile flow

  1. Install the APK on the phone.
  2. Open the app.
  3. Enter the remote VPS codex_xremote URL.
  4. Enter the codex_xremote password.
  5. Choose notification mode:
    • Current active turn only
    • All turn completions
    • Off
  6. Allow Android notifications.
  7. On Samsung One UI, set battery usage to Unrestricted and add the app to Never sleeping apps if needed.

Runtime behavior

  • Browser web keeps same-origin cookie auth.
  • Android uses /codex-api/mobile-auth/login to exchange password for a mobile token.
  • HTTP requests use Authorization: Bearer <token>.
  • WebSocket and SSE use the saved mobile runtime server URL and token-aware transport helpers.
  • If the server returns 401, the app reopens the mobile setup sheet and asks for the password again.

Notification behavior

  • Foreground: in-app sound and optional vibration
  • Background with app still alive: Android local notification
  • App force-closed: no guarantee

Validation checklist

npm run build
npm run test:smoke
npm run cap:sync

Manual Android checks:

  1. First-run setup screen appears
  2. Wrong password shows an error
  3. Correct password connects and survives app relaunch
  4. Background turn completion triggers a notification
  5. Android back closes open settings sheets and skill detail modals before navigating away

Notes

  • This shell is designed for a single remote VPS codex_xremote endpoint at a time.
  • server.url mode is not used; the APK serves local assets and only the API transport is remote.
  • If you change Capacitor major versions later, re-run npm install and npm run cap:sync before opening Android Studio.