6.5 KiB
Config transfer (Android and iOS)
Both platforms export and import the same JSON config document, so a config pulled from one phone can be pushed to either platform.
scripts/pull_config.sh # Android -> faceclaw_settings.android.json
scripts/push_config.sh # faceclaw_settings.android.json -> Android
scripts/pull_config_ios.sh # iPhone -> faceclaw_settings.ios.json
scripts/push_config_ios.sh # faceclaw_settings.ios.json -> iPhone
scripts/pull_config.sh && scripts/push_config_ios.sh faceclaw_settings.android.json # Android -> iPhone
scripts/pull_config_ios.sh && scripts/push_config.sh faceclaw_settings.ios.json # iPhone -> Android
Push also accepts legacy Android shared-preferences XML (faceclaw_settings.xml
from older pull_config.sh). Pulls write files with mode 600; the default
filenames are gitignored. Configs contain API keys and Terminal tokens: treat
them as secrets.
Format
{
"schema": 2,
"platform": "android",
"appVersion": "0.8.3",
"settings": {
"display.timeFormat": "24h",
"terminal.autoReconnect": true,
"terminal.connections": [{ "id": "c1", "url": "g2mirror://token@host:8737", "enabled": true }]
},
"platformSettings": {
"deviceAddress.left": "EC:D7:82:69:3C:CB",
"notifications.sources": [{ "packageName": "com.tailscale.ipn", "appName": "Tailscale", "showOnGlasses": true }]
}
}
settingsare imported on any platform.platformSettingsare imported only whenplatformmatches the phone importing them. They are the settings that would be wrong on another phone: the paired glasses and ring, onboarding state, notification sources (Android package names vs iOS bundle IDs), Android media apps, file paths (Files bookmarks, Teleprompter recents), installed EvenHub packages, per-phone device IDs andios.*internals. The list isSettingsTransfer.isPlatformLocalinnative/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/settings/SettingsTransfer.kt; every other setting is portable, including ones only one platform uses today, so they survive a round trip through the other platform. An enum value one platform doesn't offer (e.g. the Android-only "external" assistant backend) is harmless: each setting reads as its default when its stored value isn't one of its choices.- Values are strings, booleans and numbers, as the app stores them. Settings stored as JSON text (connections, folders, fonts, timers, EvenHub app storage, ...) are written as real JSON objects/arrays when that round-trips exactly; on import any object/array is stored back as its compact JSON text.
Schema 1 (a flat settings object, from older iOS pulls) is still accepted; its keys
are sorted into portable and platform-local at import time. When editing by hand,
move a key between the two sections to control whether it crosses platforms.
Semantics
Push merges: settings the file doesn't mention are left alone, so a cross-platform
import keeps the target phone's pairing and other platform-local settings. To clear a
value, supply its empty/default value. Malformed files, null values and files over
2 MiB fail before the device is touched (scripts/config_document.py) or before
anything is written (the phone re-validates with the same Kotlin codec).
Each import first saves the previous settings: Android writes a config document to
the app's private files/faceclaw-settings-previous.json; iOS saves its preferences
to Library/FaceclawConfigPort/previous.plist. Both apps restart after an import.
Storage itself is unchanged and per-platform. Android keeps settings in
shared_prefs/faceclaw_settings.xml, except the pairing, onboarding and EvenHub
localStorage keys, which still live in NativeScript's prefs.db.xml; the export reads
and the import writes each key in the file the app reads it from
(FaceclawSettingsPortReceiver.nativeScriptKey). iOS keeps everything in its
NSUserDefaults app domain.
Android
pull_config.sh / push_config.sh drive FaceclawSettingsPortReceiver with
am broadcast, which works on debug and release builds (release builds refuse
run-as). The receiver is guarded by android.permission.DUMP, so only the adb shell
can trigger it. The document is shuttled through the app's external files dir and
deleted as soon as it has been read. An import writes through the app's live
SharedPreferences, then exits the app so its next launch starts from the imported
settings. Pass -s SERIAL (or other adb options) to pick a device.
iOS
Requires Xcode, Python 3, a development build with FaceclawConfigPort, and an
unlocked/trusted iPhone. Both commands restart Faceclaw, briefly interrupting its
Bluetooth and Terminal sessions.
scripts/pull_config_ios.sh -f /tmp/settings.json --device IPHONE_UDID
scripts/push_config_ios.sh faceclaw_settings.xml # legacy Android pull_config.sh output
Use --device / -d or set IOS_DEVICE when more than one device is connected.
Without either, the script selects the only device with an active Xcode tunnel.
For the simulator, add --simulator (defaults to booted; --device selects one).
scripts/resetOnboardingIos.sh is the iOS counterpart of scripts/resetOnboarding.sh.
It pulls the config, then pushes every onboarding.* key that is set back to its empty
value, which the app reads the same as a missing key. Pushes can't remove keys, and the
plist can't be edited directly (see below). Its --all uninstalls the app, since iOS has
no equivalent of pm clear.
Transfers use devicectl app-container access. The app consumes a uniquely
identified request at bootstrap, before loading settings getters and workers;
it applies imports through NSUserDefaults rather than overwriting a plist that
cfprefsd could restore from cache. Replies are checked against the request ID, so a
stale export cannot appear to confirm an import. Scripts do not print values and
remove their private temporary directory on exit. Device request/reply/backup files
stay in the private Library directory, outside Files/Finder Documents.
Terminal's configured g2mirror:// scheme uses plain WebSockets; g2mirrors://
uses TLS. The iOS build declares local networking and an explicit ATS exception
for the current development server 100.68.94.67. On iOS 17+, another literal IP
requires its own build-time NSExceptionDomains entry, or a TLS endpoint. The
exception does not disable TLS certificate verification. See Apple's
IP exception rules.