Physical iPhone
Prepare an authorized Mac, pair the device, enable Developer Mode, and provision the signed XCTest runner. Device trust and protected authentication keep their native requirements.
iPhone setup guide →Computer or VM · Mac, Windows & Linux
Install the app. Connect your agent.
Start with Machine Control on the computer you want to use. The desktop app includes the control CLI and its Python runtime, so your agent can use it without cloning the repository or installing Python separately.
Need to create or prepare a VM first? Start with the VM toolbox and setup guides.
Your first desktop session
Four steps to useful control.
- 01
Install and open Machine Control
Choose the download for your operating system and architecture. Install on your physical computer or inside the VM you want to control. The app runs in the menu bar or tray.
- 02
Follow Permissions
On Mac, enable Accessibility and Screen Recording. On Linux, approve GNOME screen/input sharing when needed. For browser control, follow Chrome extension setup in the app.
- 03
Point your agent to the bundled CLI
Give an agent that can run commands the prompt below. It can read the CLI's agent instructions and discover your installed control surface. Installed CLI locations and discovery
- 04
Choose access, then start the task
Enable selected scopes and duration in Access, or approve a native request. Turn access off whenever you need to. On Mac and Windows, Pause and Resume let you temporarily stop control. Review activity in the app.
Desktop grants normally apply to callers running as your user. They do not contain an agent with an unrestricted same-user shell. Read the access boundaries.
Your choice of agent
Give your agent a task and a target.
Replace the two placeholders. Use your computer, a configured VM, or a prepared physical device as the target.
Use the installed Machine Control app to help me with <task> on <target>.
Find its bundled control CLI and read its agent instructions. If discovery
is unclear, use https://machinecontrol.dev/getting-started/ and the linked
installed-CLI guide. Inspect target readiness and available capabilities.
Use only the scopes I authorize. Request approval when needed, respect Pause
and Stop, and obtain control-session ownership where the platform requires it.
Prefer native UI and browser controls, with screenshots and input as needed.
Verify the observed result of your actions and report any uncertainty.
For a configured VM, run the read-only doctor and acquire an exclusive claim
before meaningful use. Renew it while working and release it during cleanup.
For physical devices, follow their setup, exact selection, and lease rules.
Use outer console input only for explicitly authorized bootstrap or recovery.Physical devices and remote computers
Prepare the device you want to reach.
iPhone and Chromebook control have their own setup. These routes use native device tools and the common CLI, rather than a desktop installer on the device.
Chromebook
Use a dedicated developer-mode Chromebook and follow its bootstrap guide for native desktop, browser, capture, and input access.
Chromebook setup guide →Optional capabilities
Go further when you need it.
Locked-screen access on Mac and Windows requires explicit opt-in, helper preparation, and supported platform conditions. Use theMac guideor Windows guidebefore enabling it.
For source checkouts, headless use, scripts, claims, and isolated VM workspaces, follow the CLI guide. Linux dependencies and installation details are in theLinux guide.