Install the mobile app

The ScaiClip mobile app is a Progressive Web App (PWA). Open the URL, tap "Add to Home Screen", and it installs like a native app — icon, splash screen, standalone display, offline-capable shell. No store submission, no download queue.

Roadmap note. M4 v0.3 ships cross-suite decrypt (mobile now opens HPKE-ChaCha20 wraps as well as NaClBox), team channels (mobile subscribes and receives team clips, with a publish-target picker in the UI), and background wake via Web Push (opt-in per install). Full desktop ↔ mobile sync for text AND images across all wrap suites and channel kinds.

Prerequisites#

• A modern mobile browser: Safari 17.4+ (iOS 17.4 or later) or Chrome / Edge 122+ on Android.
• A ScaiGrid API key with scaiclip:read and scaiclip:write.
• HTTPS access to your ScaiGrid host (PWAs require HTTPS except on localhost).

Install (Android)#

1. Open Chrome (or Edge / Samsung Internet).
2. Navigate to https://your-scaigrid-host/v1/modules/scaiclip/mobile.
3. Tap the browser's overflow menu → Install app (or Add to Home screen).
4. Confirm the install. The ScaiClip icon appears on your home screen.
5. Launch. Enter your ScaiGrid host + API key. On first launch the device generates fresh keys and enrols against POST /devices.

Install (iOS / iPadOS)#

1. Open Safari.
2. Navigate to https://your-scaigrid-host/v1/modules/scaiclip/mobile.
3. Tap the Share icon → Add to Home Screen.
4. Confirm. The icon appears on your home screen.
5. Launch. Enter host + key. First launch enrols.

iOS 17.4+ is required for the modern clipboard + WebCrypto APIs used by the app.

First run — enrol your device#

The mobile app never sends your private keys anywhere. On first launch:

1. It generates a fresh X25519 KEM keypair (for wraps) and Ed25519 signing keypair (for envelope signatures) via tweetnacl.js — pure JavaScript, runs entirely on your phone.
2. Keys persist locally in IndexedDB. Wiping browser data or uninstalling the PWA deletes them.
3. Public keys are sent to ScaiKey via POST /v1/modules/scaiclip/devices for enrolment. Only public keys leave the device.

Everyday use#

To copy a clip from another device to your phone:

1. Copy something on your laptop (daemon publishes).
2. On your phone, open the PWA. It reconnects and you should see the new clip in the recent-clips list.
3. Tap Copy next to the clip to write it to your phone's clipboard. Paste wherever you like.

The reason for the manual Copy step: iOS blocks clipboard writes without a user gesture. Every paste is one tap. Android is more permissive but the flow is the same for consistency.

To publish a clip from your phone:

1. Copy text or an image on your phone (any app — Notes, Photos, Screenshots, browser, whatever).
2. Open the ScaiClip PWA.
3. Tap Copy from clipboard & publish (the button pinned at the bottom).
4. iOS/Android prompts for clipboard permission on first use; grant it. The PWA prefers the richer clipboard.read() API so it picks up PNG images when available; if nothing image-shaped is on the clipboard it falls back to readText().
5. The clip encrypts and publishes. Text goes inline; images go via central scratch storage with a MediaRef pointer. It appears on every other enrolled device within ~250 ms of that device coming online.

Image support. Images are transported as ref_scratch clips — the mobile app uploads the ciphertext to Garage-backed scratch storage and publishes a small envelope with a MediaRef pointer. The receiving side runs scratch.get, fetches the ciphertext, decrypts, and renders inline. Both directions work (screenshot on phone → daemon; screenshot on laptop → phone gallery via Save).

Foreground vs background#

PWAs on iOS cannot run background WebSockets. On Android they can, but battery-optimisation kicks in eventually. Web Push wake covers the gap:

• You keep it open → constant real-time sync via WebSocket.
• You backgrounded it → the PWA registers a Web Push subscription (tap Enable background wake on the connected view). When your ScaiGrid server has a new clip for you, a wake notification lands ("New clip available"). Tapping it re-focuses the PWA which reconnects the WS and displays the clip.

Privacy. The wake push carries no clip content — the payload is empty. The clip itself never touches your browser vendor's push infrastructure; end-to-end encryption still holds. The push is a doorbell, not a delivery truck.

Uninstall#

Android: long-press the app icon → Uninstall (or drag to trash).

iOS: long-press the icon → Delete App → Delete from Home Screen or Delete App (the second option wipes the PWA's IndexedDB).

To also revoke the device from ScaiKey (so your published clips stop being wrapped for it), open your ScaiKey device console and remove the entry named "ScaiClip mobile …".

What v0.3 delivers#

Troubleshooting#

"Not connected" on launch — check the host is HTTPS and reachable. Watch the log panel; connection errors surface there.

"enrol: 401" — API key doesn't have the required scopes. Regenerate with scaiclip:read + scaiclip:write.

Clipboard read fails / silent — iOS requires a user gesture per read. The Publish button acts as the gesture; tapping it triggers the read.

Clips show as (encrypted — cross-suite compat in v0.2) — the sender used the daemon's HPKE-ChaCha20 wraps. v0.2 either updates the daemon to emit NaClBox wraps for mobile targets or the PWA to decrypt legacy HPKE.

App won't install — check you're on a supported browser + version. iOS below 17.4 lacks the crypto APIs needed for PWA installation of this app.

What's next#

• Two-device round trip — the manual client walkthrough.
• Install the T1 daemon — the desktop counterpart.
• Encryption & consent — what the mobile app is doing under the hood.