Everything Mobium needs on the machine and on the device, for all four kinds of target. Written from doing it: every trap below cost real time here, and most of them report something that names the wrong cause.
Run mobium doctor first. It checks the whole list without needing a
device, and exits non-zero if it found something:
ok adb Android Debug Bridge version 1.0.41 at /opt/homebrew/bin/adb
note android sdk root ANDROID_SDK_ROOT is not set — only needed to start emulators, not to drive them
note android devices none running — start an emulator or plug in a phone
ok xcode /usr/bin/xcrun
note ios simulators 11 available, none booted — `xcrun simctl boot <udid>`
ok simulator runner WebDriverAgent 16.12.8 for arm64 — Apple Silicon
ok daemon socket ~/.mobium/daemon/mobium.sock (46 bytes of ~104)
ok device agents cached: uiautomator2 10.6.6, webdriveragent 16.12.8 (iOS simulators, arm64), webdriveragent 16.12.8 (Apple TV simulators, arm64)
note third-party drivers none on PATH — a driver is an executable named mobium-driver-<name>, used with --driver <name>
everything mobium needs is here
note means something is missing that is only needed for part of the job —
no Xcode on a machine doing Android work is normal, not a problem.
- Installing a release — no Go needed, from the first release
- Android emulator
- Android real device
- iOS simulator — and an Apple TV simulator
- iOS real device — native screens, WebViews and Safari
- Parallel runs — one daemon for each
- Driving another machine's devices —
--remote, and a grid - What Mobium installs, and removing it
Every release, from v0.1.0-rc1 on, carries mobium prebuilt for
macOS, Linux and Windows, on amd64 and arm64, so installing it needs no Go:
mobium_<version>_<os>_<arch>.tar.gz (.zip for Windows), each holding the
binary, the license and its notices, and the README, and SHA256SUMS over
all of them. The binary is static — nothing else to install with it.
v=0.1.0-rc1; os=darwin; arch=arm64 # the release you want; os linux, arch amd64 (Windows: the .zip)
base=https://github.com/mobiumdev/mobium/releases/download/v$v
curl -LO "$base/mobium_${v}_${os}_${arch}.tar.gz" -LO "$base/SHA256SUMS"
shasum -a 256 -c --ignore-missing SHA256SUMS # must say OK
tar -xzf "mobium_${v}_${os}_${arch}.tar.gz"
mv "mobium_${v}_${os}_${arch}/mobium" /usr/local/bin/ # or anywhere on PATH
mobium --versionOn macOS, download with curl, not a browser. The binaries are not
notarized — that needs an Apple Developer Program membership — and macOS
blocks a quarantined, un-notarized download from a browser at first launch.
curl does not quarantine what it saves. For a copy that came through a
browser, xattr -d com.apple.quarantine mobium lifts it, after checking its
checksum.
brew install --cask android-commandlinetools
export ANDROID_HOME=/opt/homebrew/share/android-commandlinetools
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH="$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$PATH"
yes | sdkmanager --licenses
sdkmanager --install "emulator" "platform-tools" \
"system-images;android-35;google_apis;arm64-v8a"
avdmanager create avd -n mobium-test -d pixel_7 \
-k "system-images;android-35;google_apis;arm64-v8a"
emulator -avd mobium-test -no-snapshot-save -no-boot-anim &
adb wait-for-deviceOr let Mobium start it: mobium boot mobium-test cold-boots the AVD headless
(--window to see it) and answers with its serial once it has booted, and
mobium shutdown emulator-5554 ends the session on it and shuts it down.
sdkmanager and avdmanager need a JDK. If they fail with a Java error:
export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/HomeGoogle ships the command-line tools as a zip, and the emulator and
platform-tools for Linux only for x86_64 — the SDK repository has no
Linux arm64 build of either (checked 2026-09-28) — so an arm64 Linux machine
cannot run the emulator. The emulator needs KVM: your user must be able to
open /dev/kvm (usually by being in the kvm group).
mkdir -p ~/android-sdk/cmdline-tools && cd ~/android-sdk/cmdline-tools
curl -LO https://dl.google.com/android/repository/commandlinetools-linux-16111833_latest.zip
unzip commandlinetools-linux-16111833_latest.zip && mv cmdline-tools latest
export ANDROID_HOME=~/android-sdk
export ANDROID_SDK_ROOT=$ANDROID_HOME
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$PATH"
sdkmanager --install "emulator" "platform-tools" \
"system-images;android-35;google_apis;x86_64"
avdmanager create avd -n mobium-test -d pixel_7 \
-k "system-images;android-35;google_apis;x86_64"
emulator -avd mobium-test -no-snapshot-save -no-boot-anim &
adb wait-for-deviceRun that way on Ubuntu 24.04 on 2026-09-28, with a JDK 17, and every quick-start page passed. Three things it showed:
sdkmanagersays it is deprecated and hands over to the new Android CLI (android sdk), downloading it on first use. It still installs what it is asked for;--licensesis no longer needed.- The Pixel 7 profile needs 12GB free for its data partition. With less,
emulatorexits at once withNot enough space to create userdata partition— in its log, not on the terminal — andadb wait-for-devicewaits forever for a device that is not coming. - On two cores it is slow the first time. The emulator warns that it wants four. On a freshly booted one, the first tap into Network & internet took 10.5 seconds to open the screen — past the quick start's 10-second wait once in two runs — and 4.3 seconds later on; on a Mac it takes under one.
Add -no-window. Everything mobium does works unchanged, screenshots
included — adb exec-out screencap reads the framebuffer, not the window:
emulator -avd mobium-test -no-window -no-snapshot-save -no-boot-anim -no-audio &Unlike an iOS simulator, the window cannot be attached afterwards. simctl boot is always headless and mobium boot <udid> --window shows it later; the Android
emulator decides at launch, and the console (adb emu help) has no command to
raise a window. To see the screen on a -no-window emulator, take a
screenshot — or restart it without the flag.
Measured on a Pixel 7 AVD, both modes A/B in one sitting, so the comparison is like for like:
-no-window |
windowed | |
|---|---|---|
map (uiautomator2), median of 5 |
0.03s | 0.04s |
screenshot |
0.18s | 0.22s |
Slightly faster, not dramatically. The real reasons to use it are that nothing steals focus and that it runs where there is no display at all. Resident memory was ~5.3–5.6GB in both, and the two readings disagreed by less than they varied, so treat them as the same.
Measured 2026-09-26, when a headless emulator was restarted with a window mid-session and three things changed at once. The screen is the same; the keyboard and the snapshot are not.
Switching an emulator between the two. It is decided at launch, so it
is a restart, in the order docs/SHUTDOWN.md gives:
mobium shutdown emulator-5554 && mobium boot mobium-test --window # headed
mobium shutdown emulator-5554 && mobium boot mobium-test # headlessmobium boot cold-boots, passing -no-snapshot-load. mobium shutdown ends
only its own daemon's session, so stop any other session on the device first
(docs/SHUTDOWN.md).
-no-snapshot-load, not -no-snapshot-save. -no-snapshot-save still
loads the quick-boot snapshot on the next start, and everything installed
since that snapshot was taken is gone — MobiumApp came back as a build from
days earlier, with screens it no longer has, and the first check to look for
a new screen reported it missing. Cold-boot, or reinstall what you need after
a restart and confirm its version.
The keyboard is the difference that matters.
| headless emulator | headed emulator | simulator | |
|---|---|---|---|
| keyboard | the full on-screen keyboard | none: the Mac's keyboard is a hardware keyboard, and Gboard shows a floating toolbar — a pill at the left edge — in its place | on-screen, until the simulator switches itself to the hardware keyboard and parks it below the screen |
mobium keyboard says |
shown | shown (Android's mInputShown is true for the pill) |
shown only while it is on screen |
| covers the bottom of the screen | yes | no — the pill covers the left edge, x 21–169 | yes, while it is up |
show_ime_with_hard_keyboard was already 1 on the headed emulator and did
not bring the full keyboard back. What follows:
- Checks that need the keyboard over something skip, and say so.
dialogs.sh's keyboard step asks whether the button is really covered — the touchable region on Android, the keyboard node on iOS — and prints SKIPPED with the reason when a hardware keyboard means nothing is. - Run keyboard checks headless, or on a simulator whose software
keyboard is showing (I/O ▸ Keyboard ▸ Toggle Software Keyboard, ⌘K). A
simulator switches on its own; check
mobium keyboardbefore blaming a check. - The pill is an obstruction worth knowing about: it covers whatever is at the left edge, and Mobium refuses a target under it (CHALLENGES 107).
Everything else is the same: screenshots come from the framebuffer
either way, and map and screenshots cost about the same (the table above).
One run per daemon session per device. Two things run against one
device at once — a check in the background and commands by hand — on the
same MOBIUM_SESSION, or on two sessions both holding that device, made
WebDriverAgent restart mid-run and drop the app to the home screen: each
invalidates the other's device-side session. Give each concurrent run its
own MOBIUM_SESSION, on its own device.
platform-toolsmust be installed into the SDK root bysdkmanager, not only as theandroid-platform-toolsHomebrew cask. The emulator validates the SDK root by looking for that directory and aborts withBroken AVD system path/Cannot find valid sdk root path— whileadbsits on yourPATHworking perfectly, which sends you looking in entirely the wrong place.mobium doctorchecks this specifically.avdmanagerprintsCould not load devices from .../devices.xml. Harmless. The device profile is applied — confirm withhw.lcd.widthin~/.android/avd/<name>.avd/config.inirather than believing the error.
Stable sdkmanager tops out at API 35 (Android 15). API 36 and 37 are
canary-channel only:
sdkmanager --channel=3 --list | grep "system-images;android-37"
sdkmanager --channel=3 "system-images;android-37.0;google_apis;arm64-v8a"Use the plain google_apis flavor to match an existing AVD; the _ps16k
variants use a different memory page size, and google_apis_playstore images
cannot be rooted.
Wear OS images are on the stable channel, Wear OS 3 to 6.1, and 7.0 at API 37. A watch is driven as any Android device, by the same backends:
sdkmanager "system-images;android-35-ext15;android-wear;arm64-v8a" # Wear OS 5.1
avdmanager create avd -n mobium-wear -d wearos_large_round \
-k "system-images;android-35-ext15;android-wear;arm64-v8a"
mobium boot mobium-wear
docs/checks/wear-os.sh <the serial it names>avdmanager prints "Could not load devices" for another image's
devices.xml and applies the profile anyway (454×454 at 320dpi). A watch
goes back by swiping right, which swipe right does; press back works
too. The crown has no command yet.
mobium boot mobium-test # emulator-5554
mobium boot mobium-test-17 # emulator-5556Each takes the next free port by itself. Started by hand, do not pass -port:
measured on emulator 37, it leaves no control port, so mobium audio is refused.
By hand, also pass -no-audio, as mobium boot does. Without it the host's audio
output breaks up what a capture hears: 151 breaks in 48 s of the same tones where
-no-audio had none. CHALLENGES 390.
Then pass --device emulator-5556 to every command, or give a client the
device option. With two ready, a call that names no device is refused, so
MOBIUM_SESSION alone does not choose one: it gives each run its own daemon
(parallel runs), and each still names its device.
A stock Google APIs image ships about 240 packages and no calculator. Whatever app you plan to test, check it is there before building a test around it. To compare against a real phone, pull the app off the phone:
adb -s <phone> shell pm path com.example.app
adb -s <phone> pull <base.apk> ; adb -s <phone> pull <split_config.xxhdpi.apk>
adb -s <emulator> install-multiple -r base.apk split_config.xxhdpi.apkVerified on a Pixel 8 Pro running Android 17. Mobium needed no code changes for real hardware; the setup is entirely on the phone.
- Settings → About phone → tap "Build number" seven times. This is what creates Developer options; without it neither debugging switch exists.
- Settings → System → Developer options → USB debugging.
- Plug in. A "Allow USB debugging?" prompt appears — accept it, and tick Always allow from this computer, or you will re-accept it every time the adb server restarts.
adb devicesshould list the serial asdevice.
adb devices tells you which stage you are stuck at:
| What you see | What it means |
|---|---|
the serial, device |
working |
the serial, unauthorized |
debugging is on; the prompt is waiting on the phone screen — doctor flags this as a problem, not as a device |
| nothing at all | the phone is not exposing the debug interface — step 1 or 2 is missing |
The third is the confusing one, because the cable looks dead when it is not. Check whether the Mac can see the hardware at all:
ioreg -p IOUSB -w0 -l | grep -i "Pixel\|Product Name"Hardware visible but nothing in adb devices means USB debugging is off, not
a cable fault. mobium doctor makes this call for you:
FAIL android devices Pixel 8 Pro is plugged in but adb cannot see it
→ On the phone: Settings → About phone → tap Build number seven
times, then Settings → System → Developer options → enable USB
debugging...
One more, rarely: if debugging is on and still nothing appears, pull down the notification shade, tap the USB notification and change the mode from charging to File transfer. On Android 12+ this is usually unnecessary.
Android's test-automation connection silences every other accessibility service while it is open, unless it is opened not to. So on a device with TalkBack — or VoiceView, on a Fire TV — on, a read of the screen takes the screen reader away for as long as it runs, and an app that publishes its contents only to a screen reader stops publishing them (CHALLENGES 208).
Both drivers leave the screen reader running. The default, UiAutomator2,
opens its connection that way; --driver uiautomator reads through a reader
of Mobium's own whenever an accessibility service is enabled. With TalkBack
on, taps, scrolls and typing still land: Mobium's touches are injected, not
explored. Nothing in the device's settings changes either way.
docs/checks/screen-reader.sh checks it on an emulator.
On iOS, VoiceOver changes what a touch is: it moves VoiceOver's cursor, and
a double tap activates what the cursor is on. With VoiceOver on, Mobium taps
as a VoiceOver user does — tap, check, type and a dialog's button
work, more slowly — and refuses any other gesture, saying so (CHALLENGES
348). It can tell only with iOS 27 and a runner built by Xcode 27, which a
phone's is once Mobium rebuilds it; a simulator's is not.
docs/checks/voiceover.sh checks it on an iPhone.
TalkBack is not that case: Mobium's touches land with it on, at their usual
speed, since it explores only a finger's.
MOBIUM_DUMP_READER=mobium uses Mobium's reader for every read, and
=uiautomator uses uiautomator dump for every read. It is read by the
daemon, so it takes effect only if it is set when the daemon starts — set
on a later command, it does nothing. Run mobium daemon stop first.
Android 11+. The phone and the Mac must be on the same network.
-
Developer options → Wireless debugging → on.
-
"Pair device with pairing code" — it shows an address and a six-digit code. Both expire in about a minute.
-
Find the address without reading it off the screen:
adb mdns services # adb-XXXXXXXX-abcdef _adb-tls-pairing._tcp 192.0.2.20:33169 # adb-XXXXXXXX-abcdef _adb-tls-connect._tcp 192.0.2.20:43943
-
Pair against the pairing port, which is not the one on the main Wireless debugging screen:
adb pair 192.0.2.20:33169 123456
adb pair may answer protocol fault (couldn't read status message) and
have succeeded anyway — check adb devices before retrying.
A Fire TV, or anything older than Android 11, has no pairing: Developer
Options → ADB Debugging on (on a Fire TV, Developer Options appears under
Settings > Device & Software after selecting the device name seven times
in About; older Fire OS calls that menu My Fire TV),
then adb connect <tv>:5555 with the TV's IPv4 address, and accept the prompt
on the screen. Two things go wrong there, and neither says so:
- "No route to host" while ping works is macOS, not the network. An adb
server started by a background process — Mobium's daemon, or an agent's
shell — is blocked from the local network by macOS's Local Network
privacy without a prompt.
adb kill-server && adb connect <tv>:5555from a Terminal window makes macOS ask; after that it works from anywhere until the server is killed again. - The link drops every few minutes on the Fire TV measured,
error: closedthendevice offline, in latency spikes of several seconds with no packet lost.adb connectalone leaves an offline device offline;adb disconnectfirst. Mobium does both by itself before it answers that a network device is missing or offline, andmobium testwaits out a step that never reached the device (the test runner guide).
Stopping one cleanly, ADB debugging included, is SHUTDOWN.md.
Measured on a Pixel 8 Pro against a Pixel 7 AVD, same Android 17:
| real device | emulator | |
|---|---|---|
map / text, uiautomator2 |
0.63s | 0.04s |
map / text, dump backend |
3.2s | 1.96s |
screenshot |
3.1s | 0.13s |
The screenshot cost is adb exec-out screencap itself, not Mobium — raw adb
measures the same. On a real device prefer map to screenshot, and the case
for UiAutomator2 over the dump backend is stronger than on an emulator, not
weaker.
Needs full Xcode, not just the Command Line Tools. On Apple Silicon and on
an Intel Mac alike: the WebDriverAgent runner Mobium installs is the one
built for the Mac's simulators, which mobium doctor's "simulator runner"
line names. An Intel Mac's has been run on one (CHALLENGES 381); it is
limited to the Xcode versions that still run on Intel macOS.
xcode-select -p # should be inside Xcode.app
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcodebuild -downloadPlatform iOS # the runtime, if it is missing
xcrun simctl list devices available
xcrun simctl boot <udid> # boots headless — no window appears
mobium boot <udid> --window # only this puts it on screen
mobium --device <udid> mapmobium boot "iPhone 17 Pro" boots one by name or UDID and waits until it
has, and mobium shutdown "iPhone 17 Pro" ends the session and shuts it down.
simctl boot shows you nothing. It starts the runtime with no window, so
a simulator can be fully booted and driveable while the screen stays empty.
mobium boot <udid> --window opens it on screen: in Simulator.app, or from
Xcode 27.1, which has none, in DeviceHub. A DeviceHub already open is brought
forward and left on the device it shows, and the answer names the one to pick.
Mobium needs no window — xcrun simctl io <udid> screenshot works headless —
but it is the first thing anyone asks about.
Install Xcode from the Mac App Store. xcodes install has been broken
since 2026-09-11: Apple removed the /olympus/v1/app/config endpoint it uses
to fetch its service key, so it 404s immediately after the Apple ID prompt
(xcodes#490). Downloading
the .xip from developer.apple.com and running
xcodes install <ver> --path <file>.xip also works, since that skips Apple
auth entirely.
Anything needing a password or 2FA has to run in a real terminal — there is no TTY inside an agent session.
First run downloads and installs WebDriverAgent, which takes a moment and
reports progress. It is cached under ~/.mobium afterwards.
WKWebViews work, over WebKit's Remote Web Inspector rather than CDP — a Unix socket on a simulator, carrying binary property lists. Two preconditions, neither of which mobium can arrange:
# the app must be inspectable: webView.isInspectable = true on iOS 16.4+
# for Safari, enable Web Inspector:
xcrun simctl spawn booted defaults write com.apple.mobilesafari \
WebKitDeveloperExtrasEnabledPreferenceKey -bool trueAnd one thing that looks like a bug and is not: a page's inspector target
belongs to one debugger at a time. If app_context says the page never
announced a target, something else already holds it — Safari's own Web
Inspector, or a mobium daemon still switched into that page. mobium daemon stop clears the second.
Not a setup trap so much as the trap after setup: a test that passes here and has never run on hardware. A simulator mimics the OS, not the device, so none of this exists to be driven —
Camera, motion (accelerometer and gyroscope), proximity sensor, ambient
light sensor, barometer, Bluetooth, and audio input. Face ID and Touch ID
are simulated outcomes rather than recognition: the simulator can be told
the match succeeded or failed, which exercises an app's branches and proves
nothing about the sensor. mobium biometric does the telling — and on an
Android emulator, a fingerprint's — and a real phone refuses it.
Calls, SMS and anything behind them, including 2FA. Worth contrasting with
Android, where the emulator is the only thing that can be made to ring —
adb emu drives a call lifecycle and a real handset cannot be driven that way
from outside. The capability runs in opposite directions on the two platforms.
The binary you ship. simctl install takes a .app built against the
simulator SDK. The .ipa that goes to the App Store is device-signed and for a
different architecture, so nothing about signing, entitlements or store
packaging is exercised on a simulator. This is also why somebody's shipped
app could not close the hybrid-app gap here, and
MobiumApp was built instead.
The Android emulator has its own list — no Bluetooth, NFC, SD card insert/eject, attached headphones or USB — and it is a different list, which is the point. Neither substrate is a subset of the other.
The background, and the argument for which stage of a pipeline each device belongs to, is in Emulator vs Simulator vs Real Device.
Verified on a tvOS 26.5 simulator (Apple TV 4K, 3rd generation, at 1080p) with Xcode 26.6, on 2026-10-09. The tvOS platform is a separate download:
xcodebuild -downloadPlatform tvOS # or Xcode > Settings > Components
xcrun simctl create "Apple TV" \
com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-3rd-generation-1080p \
com.apple.CoreSimulator.SimRuntime.tvOS-26-5
mobium boot <udid> --windowmobium devices lists it as an apple tv simulator, and the first command
installs WebDriverAgent's tvOS runner, from the same pinned release as the
iOS one and checked the same way. It is driven with the remote, as a Fire TV
is: press dpad-up, dpad-down, dpad-left, dpad-right and select,
each D-pad press reported by where focus went; back is the remote's Menu
button, and play-pause is the Siri Remote's only media key. There is no
touch screen, so tap and every other gesture are refused, and so are
alert accept and dismiss: an alert opens with focus on its cancel button
and is answered by moving focus and pressing select.
checks/tv-app.sh drives
MobiumTV on it,
the same check as on an Android TV.
Verified on an iPhone 15 Plus running iOS 26.6.2, over USB, with Xcode 26.6,
on 2026-09-22. Native screens are driven exactly as on a simulator —
map, tap, type, scroll-to, wait, screenshot, launch,
terminate, apps, uninstall, press home.
checks/ios-device.sh is the flow, end to end.
- Connect it with a cable, unlock it, tap Trust This Computer and enter the passcode.
- Open Xcode → Window → Devices and Simulators with the phone connected, and wait while Xcode prepares it. The next step's switch does not exist until this has happened.
- Settings → Privacy & Security → Developer Mode → on. The phone restarts and asks you to confirm.
- Settings → Developer → Enable UI Automation → on. Without it WebDriverAgent installs, launches, and fails with "Timed out while enabling automation mode", which does not say which switch.
- Settings → Display & Brightness → Auto-Lock → Never while you work, or long enough that it will not lock mid-run. Low Power Mode forces 30 seconds and grays the setting out.
Xcode → Settings → Accounts → add an Apple ID. A free one works. Then Manage Certificates → + → Apple Development, if Xcode has not made one.
That is all. Mobium reads your development team from the certificate — its
OU field is the team id — and on the first command against the phone it
downloads WebDriverAgent's pinned, checksummed source, builds it signed for
your team and the phone, and starts it. About 20 seconds when that was
measured; a minute or two is not unusual. macOS may ask once whether
codesign may use the key: Always Allow, or it asks for every file it
signs, every build.
If the keychain holds certificates for more than one team, Mobium refuses to
guess: set MOBIUM_IOS_TEAM=<team id>.
mobium devices # the phone is listed as "ios device"
mobium --device <udid> mapA device named by --device needs no --driver: an iPhone or a simulator
is driven by wda, the only driver either has.
With exactly one iOS device available — one booted simulator, or one
connected phone — and no Android device connected, --device and
--driver can both be left out: a call that names neither goes to the only
device there is. Android stays the default when any Android device is
connected, so with both platforms connected, name the device. With several
iOS devices and no Android one, a call that names none is refused, listing
them.
Apple documents seven days for a profile made with a free Apple ID. The one
Xcode made for the account this was verified with expires on 2027-09-23, a
year out, so check yours: when it lapses the runner stops launching, and
removing ~/.mobium/webdriveragent-device/ makes Mobium build a fresh one.
These are done by simctl on a simulator and devicectl has no equivalent,
so on a phone they are refused, each with the reason, rather than
approximated: permissions, appearance, the clipboard, simulated location
and routes, and notifications — reading or posting them.
Clearing an app's data takes its bundle on a phone. Nothing can delete
from an app's container there, so mobium clear-data <app> --bundle <App.app or .ipa> uninstalls the app and installs it again, which empties
its container, read back, and resets its permissions. Installing over the
app without uninstalling would keep both.
Screen recording works on a phone, differently: the frames come from WebDriverAgent's screen stream, about ten a second whether or not anything moves, and are written into the MP4 on the Mac as JPEG images rather than as H.264. Apple's AVFoundation, which QuickTime Player is built on, opens and decodes it (measured); browsers are not known to play JPEG video in an MP4, and none has been tried.
They work on a phone, reached through the phone's lockdown service and speaking the same protocol as a simulator's. It needs the phone connected by cable — usbmuxd, which carries it, is USB — and:
- an app's WebView is inspectable only if the app sets
isInspectable = true, on a phone exactly as on a simulator. Wikipedia's App Store build does not, and its articles are read through the native tree instead, where their links are mapped; - Safari needs Settings > Apps > Safari > Advanced > Web Inspector on
— Apple's documented switch for remote inspection, and on a simulator the
measured one (its equivalent
defaultskey). On the phone this was verified with it on; it has not yet been measured with it off. Remote Automation, on the same page, is Apple's switch for WebDriver automation of Safari, which Mobium does not use.
Tapping inside Safari's page was refused on a phone as on a simulator: the
page cannot say where it sits under Safari's own chrome (CHALLENGES 47).
Since CHALLENGES 248 that is read from text the page and the WebView both
report, which places a tap exactly on a phone as on a simulator: on the
iPhone 15 Plus a tap on example.com's "Learn more" opened the page it links
to. Reading, mapping and eval work either way.
A phone reads a screen in about 2 seconds for Settings and 6 for the home
screen, against a fraction of a second on a simulator; a screenshot takes
0.5s. Prefer map to screenshot for the same reason as on Android.
The first read after switching apps can stall for a minute and return the
app you just left (CHALLENGES 71). Mobium prevents it for
the switches it makes itself — launch and press home — by telling
WebDriverAgent which app is coming. A tap that opens another app gives no
such warning, so after one, a slow first read is that and not a hang.
Give each run that drives a device at the same time as another its own
daemon. One daemon serves one call at a time, across every device it
holds, so two runs sharing one go at the pace of the slower device.
Measured on 2026-09-27, 15 map calls on each of an Android 15 emulator and
an iPhone 17 Pro simulator at once:
| the emulator's 15 calls | |
|---|---|
| alone | 0.3s |
| sharing a daemon with the simulator's | 22.3s |
| on a daemon of its own, while the simulator's ran on another | 0.3s |
A daemon is named by MOBIUM_SESSION, and every client can set it for the
connection it opens:
| CLI | MOBIUM_SESSION=android-run mobium map |
| Python | mobium.start(platform="android", session="android-run") |
| JavaScript | start({ platform: 'android', session: 'android-run' }) |
| Go | mobium.Start(ctx, mobium.WithPlatform("android"), mobium.WithSession("android-run")) |
| Java | Mobium.builder().platform("android").session("android-run").start() |
| .NET | Device.Builder().Platform("android").Session("android-run").Start() |
The option wins over a MOBIUM_SESSION already in the environment. Keep the
name short: it is part of a socket path, and the OS caps those at about 104
bytes. And one device belongs to one run at a time — two daemons driving the
same device invalidate each other's device-side session (above, under
"Headed and headless").
Two simulators at once work. Every simulator's WebDriverAgent listens on
the Mac itself, and until 2026-09-28 all of them on port 8100, so a second
simulator's daemon reached the first simulator's runner and drove it while
reporting it as its own. Each runner is now given free ports of its own when
it starts; two iPhone simulators on two daemons, ten map calls each at
once, each saw only its own screen. Nothing needs setting for it
(CHALLENGES 148).
Android never shared a port. Its UiAutomator2 server listens on each
device's own loopback, and mobium reaches it through adb forward tcp:0,
for which adb picks a free port on the Mac per device — as it does for each
WebView. Measured on 2026-09-28 with two emulators on two daemons: forwards
on host ports 52360 and 52527, both to their own device's 6790, and ten
map calls on each at once, each seeing only its own screen.
--remote <node>, or MOBIUM_REMOTE=<node>, drives the devices plugged
into another machine, over SSH. Every command takes it, and so does
mobium pipe, which is how all five clients connect — so a client goes
remote with the environment variable alone, and no change to its code.
What happens: mobium asks the node, over SSH, to have a daemon running and
say where it listens (mobium daemon up); forwards that socket to one in a
private directory here, owner-only; and sends every call through it. Nothing
new listens on a network — SSH authenticates and encrypts, and the node's
daemon socket stays owner-only on the node. Files travel as content
(MOBIUM_FILES=content, set for you): install's app and a GPX route go to
the node, and a screenshot or a recording comes back and is saved where you
asked. If the node's daemon stops answering, the call fails; a daemon is
never started here in its place, which would drive this machine's devices
under the node's name.
What it needs:
| SSH without a prompt | key-based login to the node; mobium runs SSH with BatchMode=yes, because a prompt would land in the stream a client speaks. MOBIUM_SSH replaces the ssh command, options included — ssh -i ~/.ssh/node_key |
| mobium on the node | reachable by the node's non-interactive shell. MOBIUM_REMOTE_BIN is what that shell runs as mobium, and may set its environment — PATH=/opt/homebrew/bin:$PATH ~/bin/mobium — when adb or Xcode's tools are not on the default PATH there |
| macOS or Linux here | the forward ends in a Unix socket; on Windows --remote refuses, and says so |
Commands about this machine stay here: daemon, doctor and mcp ignore
--remote. One device still belongs to one run at a time, on the node as
anywhere. Verified with this Mac standing in for a node: the CLI and an
unchanged Python client ran sessions, maps, installs, screenshots and
recordings on the node's daemon, every file landing on the caller's side.
MOBIUM_GRID=node1,node2 spreads runs over several machines' devices,
with no hub. At a run's first call — which is where it
says what it wants: a serial, or platform when it starts a session — mobium
asks every node over SSH for its devices and which of them are held, takes
the first free one that matches, and connects to its node as --remote
would. The lease that keeps a device to one run lives on the node, so runs
started on different machines cannot take the same device. With nothing free
that matches, a run waits, asking again every two seconds, up to
MOBIUM_GRID_WAIT (default 60s), and then says what was busy and which
nodes did not answer. A node that does not answer within five seconds is
left out, and routing goes on without it.
MOBIUM_GRID_MODEL narrows it to a model — part of its name, in any case —
and MOBIUM_GRID_OS to an OS version, matched at the start of a word, so
17 means Android 17 and its point releases and iOS 26 an iOS 26 runtime.
The node enforces a lease; mobium does not merely respect it. Each run
gets a daemon of its own on its node, named by its lease, and every daemon
on the node refuses a device leased to another: a mobium --device run on
the node that goes around the grid is told the device belongs to a grid run
until that run ends. The run's daemon stops with it.
A node lends its emulators and simulators, and a phone only when it says
so. A phone plugged into a node is usually somebody's, and a grid run on it
would install, tap and change settings; so a physical device is routed to
only when the node's own environment sets MOBIUM_GRID_PHONES=1 — the
node's choice, never the caller's. Until then it is listed as not offered,
and a run that asks for it by serial is told so.
mobium grid status prints each node's devices — platform, OS, model,
state — who holds each and for how long, the nodes not answering, and the
runs waiting. mobium grid ui serves the same as a page, refreshed every
few seconds, on 127.0.0.1 only. Both read the nodes' own answers, the ones
routing reads, so neither can disagree with where runs go.
$ mobium grid status
NODE DEVICE PLATFORM OS MODEL STATE HELD BY
lab-mac emulator-5554 android Android 15 sdk_gphone64_arm64 device g5c1e9a07 for 42s
lab-mac emulator-5556 android Android 17 sdk_gphone64_arm64 device free
waiting:
g0d4f2b11 wants an android device, OS 15, waiting 9s (seen by lab-mac)
A lease is renewed every 20 seconds while its run lives, released when it ends, and free again 60 seconds after a run that died without releasing it. A run killed outright takes its SSH forward with it, and the next run clears what it left on this machine. Each CLI command is a run of its own, so a series of them may land on different devices: a client, whose run lasts as long as it does, is the way to keep one.
Verified with this Mac standing in for a node with two emulators, and a second node that does not exist: three Python clients asking for Android at once got the two emulators, the third waited until one was released and got it, and no lease, forward or directory was left.
On the machine, under ~/.mobium:
uiautomator2/, webdriveragent/ |
pinned, checksummed device agents, ~40MB, downloaded on first use |
webdriveragent-device/ |
WebDriverAgent's pinned source and one signed build per team and phone, ~150MB — only once a real iPhone has been driven |
daemon/ |
socket and PID file, removed on shutdown |
On an Android device, the default backend installs two APKs —
io.appium.uiautomator2.server and io.appium.uiautomator2.server.test.
Nothing else, and nothing at all with --driver uiautomator.
On an iOS simulator, com.facebook.WebDriverAgentRunner.xctrunner.
On a real iPhone, dev.mobium.wda.<team>.xctrunner, signed for your team
and named MobiumWDA-Runner. Another tool that installs its own WebDriverAgent
removed every runner named WebDriverAgentRunner-Runner before installing its
own, and left this one alone (measured, CHALLENGES 189). If it
is removed anyway, the next session says so as it installs it again.
Mobium stops it when the session ends; mobium --device <udid> uninstall dev.mobium.wda.<team>.xctrunner removes it. On the phone, also turn Enable UI
Automation back off and restore Auto-Lock.
To leave a device exactly as you found it:
mobium daemon stop # release the session first
mobium --device <serial> uninstall io.appium.uiautomator2.server.test
mobium --device <serial> uninstall io.appium.uiautomator2.server
mobium --device <serial> apps # should list neitherMobium reinstalls them automatically on the next run, so removing them costs nothing but the reinstall.
Finishing a session cleanly — and the order that avoids orphaning a device session — is SHUTDOWN.md.
Nothing is left in the device's filesystem. The dump backend writes a
hierarchy file to /data/local/tmp and deletes it after every read — that
file is a serialization of whatever is on screen, so on a real phone it is
your data, and it is not left behind. With a screen reader on, it pushes its
own reader to /data/local/tmp/mobium-reader instead, and deletes the folder,
with the copy Android compiles into it, after every read. Verify with:
adb -s <serial> shell ls /data/local/tmp