homeio

A small Capacitor app (Android + iOS) that connects to a self-hosted Homeio server over Tailscale.

How it works

This app is a thin native shell, not a re-implementation of the dashboard:

1. It opens on a bundled Connect screen (the only code in this project) where you add a server by its tailnet address and optional username.
2. It probes GET <address>/api/health to confirm the server is reachable.
3. It then navigates the WebView onto the server's own origin. From there the full Homeio web app runs first-party — its existing /login page handles your username/password (and TOTP), and everything (terminal WebSocket, SSE, uploads) works because the WebView is on the server's origin (no CORS, no auth re-implementation).

Network reachability is provided by the official Tailscale app, which must be installed and connected on the phone. This app does not embed the Tailscale tunnel.

See doc/modules/mobile-app.md for the full architecture.

Prerequisites

• Node.js 20+ and npm
• The official Tailscale app on the phone, signed into the same tailnet as the server
• For Android builds: Android Studio + JDK 17
• For iOS builds: macOS + Xcode

Setup

cd apps/mobile
npm install

# Add the native platforms (generated locally; git-ignored)
npm run add:android
npm run add:ios        # macOS only

# Build the launcher and copy it into the native projects
npm run sync

Run

npm run dev            # iterate on the Connect screen in a desktop browser
npm run run:android    # build + sync + launch on a device/emulator
npm run run:ios        # macOS only

Finding your server's address

On the server, run tailscale status, or open Homeio → Settings → Integrations → Tailscale. Use the MagicDNS name (*.ts.net) or a 100.x tailnet IP, with the Homeio port (default 3000), e.g. homeio.tailnet-name.ts.net:3000.

Notes

• Passwords are not stored by this app; you sign in on the server's first-party login page. Silent auto-login is a planned enhancement (see the module doc).
• android/ and ios/ are git-ignored — run cap add after cloning.
• Allowed navigation hosts (*.ts.net, 100.*) are configured in capacitor.config.ts.