# Handsy AI

> Handsy AI (ESP32 iPhone Agent) is an open-source project that lets an AI operate a real, unmodified iPhone. A $7 XIAO ESP32S3 board receives the iPhone's screen through AirPlay Screen Mirroring and acts as a USB mouse and keyboard; the ESP32 Agent iPhone app, or an agent on a computer through Handsy CLI, decides each step.

## Key facts

- Names: the product and site are Handsy AI (handsy.tech); the open-source project is ESP32 iPhone Agent; the iPhone app is ESP32 Agent; the command-line tool is Handsy CLI (`esp32agent`).
- No jailbreak, no Mac, no Xcode and no Apple developer account. iOS stays stock.
- Hardware: a standard Seeed Studio XIAO ESP32S3 (8 MB flash, 8 MB PSRAM, about $7) and a short USB-C data cable. Lightning iPhones also need a Lightning to USB Camera Adapter.
- Phone: iPhone XS or newer on iOS 18, with cellular data (the iPhone's Wi-Fi joins the board's hotspot).
- Two ways to use it: the iPhone app plans and runs tasks by itself (no computer after the one-time firmware install), or a computer agent such as Claude Code or Codex drives the phone through Handsy CLI and MCP over Bluetooth.
- AI: the app includes a free AI service; it also accepts your own image-capable, OpenAI-compatible service.
- Limits: the phone stays unlocked and in portrait; iOS does not mirror passcode entry, Apple Pay or DRM-protected video; a USB-C iPhone cannot charge by wire while the board is plugged in.
- License: MIT, except the firmware's AirPlay receiver (GPL-3.0). Source: https://github.com/onehumanbeing/esp32-iphone-agent
- handsy.tech is the only official website.
- Full docs as one file: https://handsy.tech/llms-full.txt

## Board setup

- [Install firmware](https://handsy.tech/install): Official browser installer and release availability.
- [安装固件 (Chinese)](https://handsy.tech/zh/install): The same installer in Simplified Chinese.
- [AI installation guide](https://handsy.tech/install-guide.md): User-requested setup, supported hardware, installation confirmation, troubleshooting, and verified completion.

## How it works

- [How ESP32 iPhone Agent works](https://handsy.tech/how-it-works): The ESP32-S3 is an AirPlay mirroring receiver and a USB keyboard and mouse, so an AI can see and operate a real iPhone.
- [ESP32 iPhone Agent 如何工作（中文）](https://handsy.tech/zh/how-it-works): 同一说明的简体中文版。
- [No video](https://handsy.tech/troubleshooting): The AirPlay source must be an iPhone. Screen Mirroring from macOS is not supported.
- [没有画面（中文）](https://handsy.tech/zh/troubleshooting): 同一排查的简体中文版。

## App and CLI

- [App guide](https://handsy.tech/docs/getting-started): App Store availability, board setup, phone onboarding, and a first task.
- [CLI tutorial](https://handsy.tech/docs/cli): CLI demo, install commands, Bluetooth pairing, and agent integration.
- [CLI agent setup guide](https://handsy.tech/cli-guide.md): Install, requirements, local MCP setup, and real-device verification for Handsy CLI 0.1.0.
- [Intents & recording](https://handsy.tech/docs/intents): Record a demonstration or save a run as a reusable intent; Result card; Ask me first.
- [Firmware updates](https://handsy.tech/docs/firmware-updates): Official vs TestFlight channels, in-app updates over Wi-Fi, rollback, and reinstalling over USB.
- [Hotspot vs home Wi-Fi](https://handsy.tech/docs/wifi-hotspot-vs-home-wifi): Switch the board from station mode back to its hotspot; Local Network permission.
- [Lightning iPhone](https://handsy.tech/docs/lightning-iphone-adapter): Camera adapter, power, and the accessory update loop.
- [Developer harness](https://handsy.tech/docs/harness): Open-source loop to install the app, update the board, and run tasks over Wi-Fi.

## Reference

- [FAQ](https://handsy.tech/docs/faq): Short answers on the app, AI services, limits, charging, calibration and logs.
- [Hardware](https://handsy.tech/docs/hardware): Which board and cable to buy, and how to attach the antenna.
- [Changelog](https://handsy.tech/docs/changelog): App, firmware and CLI releases by version.
- [Debugging & logs](https://handsy.tech/docs/debugging): How to collect and send diagnostics.