Mobile preview

Kunai's mobile work is a capability preview, not a supported app. There is no search, no catalog, no provider picker, no install or update path, and no playback monitoring. The preview exists to prove the terminal runtime and the VLC handoff on real hardware before anything else is built on top of it.

If that sounds like your kind of experiment, read on. If you wanted the actual app, Getting started is the supported path.

What the preview doesCopy Anchor Link

A run does exactly four things, in order:

1. Asks whether to continue; Ctrl+C or 0 cancels cleanly.
2. Makes one bounded HTTPS GET to a probe URL you provide (8 seconds, 3 redirects, 64 KiB, HTTPS only even through redirects).
3. Writes bounded state in a private directory on the device.
4. Hands one media URL to VLC (an explicit intent on Android, the vlc-x-callback scheme on iOS) and reports whether the OS accepted the request.

"Accepted" means the OS took the request. It does not prove VLC played anything; seeing the media begin is a human's job, and the preview says so itself.

No analytics, no install ID, no account, no relay, no media proxy. The probe URL is requested from its HTTPS origin, and the media URL is passed to VLC. Neither is sent to Kunai analytics. The same no-telemetry posture documented on Reliability and privacy binds the preview, only stricter: there is nothing to opt out of because nothing exists.

RequirementsCopy Anchor Link

Android

• A physical ARM64 phone (emulators are diagnostic only, not qualification)
• Termux from one official source; do not mix signing sources
• pkg install nodejs from the same Termux package source; record node --version with your device evidence
• VLC for Android, and termux-am or am resolvable

iPhone

• A physical device with current App Store a-Shell mini and VLC for iOS
• JavaScriptCore ships with iOS, so nothing else to install

Both: one credential-free HTTPS probe URL you own (under 64 KiB), one HTTPS media URL VLC can play without custom headers or cookies, and a desktop Kunai checkout to build the artifacts. Nothing is downloaded prebuilt; you build the bundle yourself and verify its hash.

Build, transfer, runCopy Anchor Link

In a trusted checkout:

bun install --frozen-lockfile
bun run --cwd apps/mobile build
bun run --cwd apps/mobile test:unit
bun run --cwd apps/mobile test:integration

apps/mobile/dist/ now holds the artifacts plus mobile-build-meta.json with SHA-256 digests for each one.

Android: copy dist/android/kunai-mobile-android.mjs to the device (adb push to shared storage is fine for transfer; copy it into private Termux storage and chmod 700 before running, and never execute from shared storage). Then in a foreground Termux session:

node kunai-mobile-android.mjs --help
node kunai-mobile-android.mjs --host-proof \
  --probe-url "https://your.example/status" \
  --media-url "https://your.example/video.m3u8"

iPhone: copy all five dist/ios/ files into a fresh a-Shell directory (Files, AirDrop, or Put File), chmod 700 the four helper scripts, then:

./kunai-mobile --help
./kunai-mobile --host-proof \
  --probe-url "https://your.example/status" \
  --media-url "https://your.example/video.m3u8"

Verify every transferred file's hash against mobile-build-meta.json before running. --help and --version must return to the prompt on their own; a command that prints and stays alive is a failure, not a slow start.

Boundaries worth knowingCopy Anchor Link

• Exit codes: 0 help, version, cancellation, or accepted handoff; 2 invalid arguments or URL; 1 state, HTTP, or handoff failure.
• URLs must be absolute credential-free HTTPS; plaintext HTTP, embedded credentials, fragments, and control characters exit 2 before any network or VLC work.
• VLC missing means the handoff is rejected with exit 1, honestly labeled.
• A second concurrent launch is refused. Android checks process ownership and can recover a verifiably stale owner; uncertain ownership requires explicit recovery. On iOS, close every session before removing only an empty session.lock directory with rmdir. Preserve uncertain Android ownership data and report the lock failure instead of deleting it.
• Quote and backslash characters in URLs are data, never evaluated; they must reach the prompt safely. Try it.
• If VLC opens but nothing plays, compare the same direct URL opened manually in VLC. Manual failure points to media, network, or player behavior; manual success points back to the handoff route.

Reporting and qualificationCopy Anchor Link

The preview graduates when one physical ARM64 Android row and one physical iPhone row pass against artifact digests from a trusted build. For each platform, report the artifact digests, device OS, Termux/Node/a-Shell/VLC versions, and each observation separately:

• Help and version return to the prompt without hanging.
• Ctrl+C and choosing 0 cancel before network or VLC work.
• The bounded HTTPS probe succeeds after choosing to continue.
• The OS accepts the VLC handoff, and media visibly begins.
• Quotes and backslashes in a tester-owned URL remain data.
• Invalid URLs fail before network or VLC work.
• A second concurrent launch is refused without damaging the first session.

On Android, also interrupt a pending probe and confirm VLC stays closed and the next run can start normally. Keep URLs, headers, cookies, raw device logs, and device identifiers out of reports. Record only redacted outcomes; deterministic tests and an accepted OS request are not physical playback evidence.

For the supported surface today, see Supported and unsupported and Providers.