Skip to main content
Open Devices in the sidebar to see every device Mobster can drive in one place. It shows each device’s state, its screen, its setup, the profiles on it and what needs you, and Mobster tells you when something does, even with the window in the background. The line under the title counts the devices and how many need you (“3 devices, 1 needs you”), or says they’re all ready. The sidebar’s Devices row counts the devices that need you.

​
Add a device

After the first run, the Devices page is where you add a device and finish setting one up. There is no Setup page.
  1. Choose Add a device (or ⌘⇧N, File › Add Device…). The page shows the ways to connect as tiles: With a cable, where every device starts, and Over Wi-Fi, which says whether Wi-Fi works on this Mac (Wi-Fi). Under them, what happens next, step by step.
  2. Plug the iPhone or iPad into this Mac with a cable and unlock it. Mobster finds it by itself. With several new devices plugged in, it asks which one you’re adding. Nothing showing up? Device not showing up? in the cable’s tile lists what to check: a cable that carries data, the device unlocked, Trust tapped, no hub between.
  3. Follow the rows: Xcode, Trust, Developer Mode, then Mobster’s helper, which installs by itself. Each row says what to press.
  4. With Wi-Fi for iPhones on, the last row is Wi-Fi: Mobster turns the phone’s Wi-Fi switch on right after Trust, and once the helper runs and the encrypted link is up, the row says to unplug it (Wi-Fi).
A device that isn’t set up shows the one step to do now on its card, with its fix: Finish setup opens the whole checklist for that device. A link from anywhere else in the app (the composer, the live view, a notification) lands on the device’s card. Mobster never types a passcode, taps Trust or turns on Developer Mode for you.

​
What a card shows

  • The device. Apple’s picture of its model, in its own finish when the phone reports one, with its screen inside. The card reads a small picture from the phone about every 3 seconds, only while the card is on screen and the window is in front. A screen that doesn’t change costs almost nothing. A phone that can’t show its screen shows it off, and one that is unplugged or shut down greys back.
  • Name, model and iOS.
  • State, as a dot and a word: Ready, Running a task, Locked, Unplugged and the rest. A phone on an experimental connection says which at the end of that line: Mirroring or Cable + Bluetooth.
  • Task. What it is doing now, and how many tasks wait for it.
  • Last good task. When a task last finished completed on it. Hover for what it was.
  • Profiles on it, as chips. A profile that is signed out says so.
  • Region check. Whether the phone’s region, language and time zone are what its profiles expect (below).
  • What needs you, in a strip at the foot: what happened, and the one thing to do.
New task opens an empty composer with that device chosen, as ⌘N does. A task you typed and didn’t send is set aside, with Undo to bring it back. Open task opens the task running on it. A simulator that is off has Start, a device you disconnected has Connect, and a set-up device has Set up again… under its ⋯.

​
What alerts you

Mobster recognizes a sign-in page or a security check from the words the app shows, in English, on the screen it reads while it checks the profile. It matches whole titles and buttons, never a row, a message or what is typed in a field, and a security check also needs a button to press on the screen. A screen that shows the profile signed in raises nothing. Mobster never follows what the screen says. A check in another language isn’t recognized. A task that confirms the profile on screen clears Signed out. A security check clears only when you choose Mark as handled, so a later task can’t hide it.

​
How alerts reach you

An alert is sent once, when its condition has held for 20 seconds. It isn’t sent again while the condition lasts, and a phone that flickers doesn’t alert twice. When the condition has been gone for 20 seconds it clears, and a new occurrence alerts again. What already holds when Mobster starts doesn’t alert: that is taken from the first read of every phone, not from a read of one.
  • In the Mac app, a macOS notification while Mobster is in the background, and a toast while you’re looking at it. Both open the device on the Devices page. They follow the notification switch in Settings.
  • To your webhook, the same condition, through the address in Settings that already carries scheduled-task alerts (Workflows, schedules and alerts): Slack, Discord, ntfy or JSON. The post names the phone and the profile handle and never a screenshot or a task’s answer. mobster alerts test checks the address.
Alerts are checked whenever something reads the phone list: the Mac app does every 5 to 10 seconds while it runs, and mobster serve does when a client calls GET /api/devices or GET /api/fleet/health. Nothing watches a phone on its own, so with the app closed and no client reading, no alert is sent until one reads.

​
Check a phone’s region before a task

A profile can say what its phone should be set to. In Settings › Profiles, under What the phone should be set to, or with region (a country code such as US), language (en) and timezone (America/Chicago) in POST /api/accounts, set any of the three. All are optional. Before a task that names a profile, Mobster compares them with the phone:
  • They match, or the profile expects nothing: the task starts.
  • One is known to differ: the task doesn’t start. The message names both values and the setting to change: “Sam’s iPhone doesn’t match @acme on Instagram: it is set to region GB where US is expected. Change Settings › General › Language & Region › Region on the phone, or change what the profile expects in Settings › Profiles, then run the task again. No action was taken.” There is no override: change the phone or the profile.
  • Mobster can’t read a value: the task starts, and the card says Not checked. Mobster can’t read the phone’s language yet, so a language you set is saved and shown as not checked, and it never stops a task.
A time zone matches when it’s the same zone under another name, such as Asia/Calcutta and Asia/Kolkata. Mobster reads the phone’s values through WebDriverAgent’s device info (currentLocale and timeZone). The helper answers for itself, not for the phone’s settings: its region follows the phone’s Region, but its language doesn’t, and its time zone can be an abbreviation such as CST. So the region is checked, a time zone is checked only when it comes as a name like America/Chicago, and the language is not checked until the helper can report it. The read is read-only, never on a phone that is running a task, in use by another Mobster or disconnected on its card on the Devices page, and kept for 5 minutes (5 seconds right before a task, so a setting you changed a moment ago counts). A security check waiting for a profile also stops its tasks, with “No action was taken.” This isn’t a pause for the profile: Mobster stops starting tasks for it until you mark the check handled. A retry that repeats the Idempotency-Key of a task that already started returns that task, whatever the phone says now; only a new request is refused.

​
API

  • GET /api/devices has connection (wda, mirroring or cable_bt) and health on every phone: {alerts, lastGoodRun, profiles, region, currentTask}. Each alert is {code, severity, message, action, since, profile?} with code one of unplugged, locked, signed_out, challenge, region_mismatch, owner_active.
  • GET /api/fleet/health answers {devices: [{id, name, state, health}], checkedAt}.
  • POST /api/fleet/health/acknowledge with {"profile": "<id>", "code": "challenge"} marks a security check or a sign-in handled. It needs the Mac app’s session when the app runs the server, and answers 503 health_busy when another Mobster process is holding the file: send it again.
  • A refused task answers 409 with code profile_challenge or profile_region_mismatch.
  • The event bus’s devices topic carries phone_alert ({device, deviceName, code, profile, title, body}).
Signals for profiles are kept in fleet-health.json beside the device list. Every change takes a file lock and reads the file again, so the Mac app and mobster mcp see each other’s signals.