> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onerep.life/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Mobile Apps Pointed at Your OneRep Install

> Install OneRep as a PWA with no toolchain, or build native iOS and Android apps with Capacitor and point them at your own backend.

There is no app store listing to install from. You get your install onto a phone in one of two ways: as a Progressive Web App (no build step required) or as a native app built with Capacitor. Both routes require your backend to be reachable from the phone — which the default `127.0.0.1` address is not.

<Warning>
  **The default backend address (`127.0.0.1`) is not reachable from a phone.** On a mobile device, `127.0.0.1` refers to the phone itself, not your server. If you build or open the app without changing this, it will install successfully, open, and then fail to sign in with no obvious explanation. Before building for a phone, set `PUBLIC_HOST` before running `./install.sh`, or update `CONVEX_CLOUD_ORIGIN`, `CONVEX_SITE_ORIGIN`, and `APP_URL` in `selfhost/.env` and re-run the installer. A LAN address like `http://192.168.1.10:3210` is enough for testing on the same network; for everyday use you want TLS and a real hostname.
</Warning>

<Tabs>
  <Tab title="PWA">
    The Progressive Web App route requires no build toolchain and no IDE. Open your install in the phone's browser and add it to the home screen:

    * **iOS (Safari):** tap the Share button, then choose **Add to Home Screen**
    * **Android (Chrome):** tap the menu, then choose **Install app**

    Once installed, the app runs fullscreen and caches content for offline use. Updates are applied automatically the next time you reload.

    **Requirements for the PWA install prompt to appear:**

    * Your install must be served over **HTTPS** on a **real hostname**. Browsers only offer the install option under those conditions.
    * `127.0.0.1` or a plain LAN IP will not trigger the prompt on iOS. Android Chrome is more permissive on local networks, but HTTPS is still required for service worker caching to work properly.

    <Tip>
      If you just want to test on a phone on your local network, a LAN address with a self-signed certificate is enough to get the PWA install prompt on most Android devices. iOS requires a certificate that the device trusts.
    </Tip>
  </Tab>

  <Tab title="Native Apps">
    The iOS and Android Capacitor projects are already checked in under `apps/mobile/ios` and `apps/mobile/android` — there is nothing to generate. You need Xcode (for iOS) or Android Studio (for Android), plus Bun installed on your machine.

    ## Configure your backend URLs

    Before building, make sure the repository-root `.env` file points at a hostname your phone can reach. These are the three variables the app build reads:

    ```sh theme={null}
    VITE_CONVEX_URL=https://convex.your-domain.tld
    VITE_CONVEX_SITE_URL=https://convex-site.your-domain.tld
    VITE_APP_URL=https://app.your-domain.tld
    ```

    These must match the values in `selfhost/.env`. If you set `PUBLIC_HOST` before running the installer, the matching `.env` values are set for you; otherwise edit them manually.

    ## Build and open in the IDE

    From the `apps/mobile` directory, build the web assets, sync them into the native projects, then open the IDE:

    ```sh theme={null}
    cd apps/mobile
    bun run build
    bunx cap sync
    bunx cap open ios      # or: bunx cap open android
    ```

    Press **Run** in Xcode or Android Studio to install onto a simulator, emulator, or connected device.

    <Note>
      Shipping to a real iPhone requires a signing team set on the Xcode target. A free Apple ID works, but Apple limits those builds to a seven-day expiry before you need to re-sign.
    </Note>

    ## Run directly on a connected device

    Once a device is attached, you can skip the IDE entirely:

    ```sh theme={null}
    bunx cap run ios       # or: bunx cap run android
    ```

    ## Keep native projects up to date

    The native projects hold a copy of the built web assets — not a live link to them. Re-run the build and sync after any change to the web app:

    ```sh theme={null}
    bun run build
    bunx cap sync
    ```

    More detail on native-specific configuration and signing is in `apps/mobile/README.md`.
  </Tab>
</Tabs>