FAQ

Do I need to leave a computer running?

With the app: no. Use a computer once to install the board firmware in your browser. Then the app and board handle the task together.

With the CLI: yes. Your agent runs on the computer and uses Bluetooth to reach the board. See CLI & AI agents for the demo, setup, and release availability.

How do I get the app?

Handsy AI is coming to the App Store. The download entry will be added when the listing is available. Getting started walks through downloading the app and setting it up.

Can I try it without my own AI service?

Yes. A free AI service is available in the app, so you can start there. You can also connect your own image-capable, OpenAI-compatible service. An API key is only needed when configuring your own service.

We plan to offer a subscription AI service in the future to make getting started even easier. See the privacy policy for how each service handles screenshots and tasks.

Can I stop or take over?

Yes. Stop from the app or the Dynamic Island. If a task needs your help, the app can send a notification: press and hold it to continue, skip a step, stop, or take over. Keep risk confirmations enabled in Settings → Runs if you want to review sensitive steps before they happen.

Why does the app use cellular data?

Your iPhone joins the board’s Wi-Fi so it can mirror the screen. That Wi-Fi connection has no internet; the app reaches your AI service over cellular data. Screen Mirroring stays on the local connection; model requests use cellular data. Keep cellular data enabled while running a task.

Bluetooth will not pair, or only works very close to the phone

Check that the included Wi-Fi/Bluetooth antenna is connected to the board. Without an antenna, Bluetooth may fail or work only with the board right beside the phone. Attach it, keep the board close to the iPhone, and try Plug Me In again.

For the connector location, see Attach the antenna.

How do I find the board’s Wi-Fi password?

With the upcoming firmware v0.2.2 and matching CLI, pair first, then run:

esp32agent wifi

It reads the hotspot name and password through the paired, encrypted Bluetooth session without changing the configuration. An active app operation has priority; wait for it to finish before retrying. The command is planned for that release and is not available in the earlier CLI.

Before that release, the password can be viewed in ESP32 Agent or read over the board’s USB serial connection:

1. Connect the prepared board to a computer by USB. Open its normal running serial port at 115200 baud.
2. Send one line: 0 netinfo.
3. For the board hotspot, confirm mode is ap, then use ssid and pass in the iPhone’s Wi-Fi settings.
4. Move the board back to the iPhone and start Screen Mirroring again. Simply reconnecting power does not change the saved hotspot password.

Keep the full serial response private: it also contains an access token. If mode is sta, the credentials describe the network the board joined, rather than its own hotspot.

The board is missing from Screen Mirroring

1. Plug in the board. For the app, finish its Bluetooth pairing; for the CLI, use esp32agent pair on your computer.
2. Keep the board close to the phone and join its Wi-Fi. CLI users can do this directly in Settings → Wi-Fi; find the hotspot password first. App users can follow the join prompt or the manual password shown there.
3. Open Control Center → Screen Mirroring → ESP32 Agent.
4. Keep your iPhone unlocked.

ESP32 Agent is the receiver name to look for in Screen Mirroring.

If joining the board’s Wi-Fi fails, move the board right beside the phone and try again. The board’s hotspot uses reduced transmit power; this is separate from Bluetooth pairing. See the connection discussion.

Mirroring is connected, but the picture is stuck

Stop the task first. If the preview stays on an old screen, Handsy can repeat actions based on that picture and appear very slow. This has been reported in issues #25 and #29.

Disconnect Screen Mirroring and connect again. Check that your iPhone is unlocked and still connected to the board’s Wi-Fi. Move to another screen and check that the preview changes before retrying the task.

If it persists, open Settings → Diagnostics → Video in the app while mirroring is on. Share what you see there with support.

The pointer is landing in the wrong place

Turn on Settings → Accessibility → Touch → AssistiveTouch, keep the pointer visible, and keep your iPhone in portrait. In the app, complete Let Me Use the Pointer. With the CLI, run esp32agent calibrate; you do not need the app for calibration.

How can I give it a better task?

Start with one clear destination, such as “Open Settings and go to Wi-Fi.” Once that works, try a longer task. A model that understands images and follows instructions well helps; each step also depends on your model’s response time and network connection.

Watch the first run. If it goes off track, stop and make the goal more specific. You can replay the run on your phone to see where it went wrong.

What are the current limits?

Keep the phone unlocked and in portrait. Locking stops Screen Mirroring. iOS does not mirror passcode entry, Apple Pay, or DRM-protected video. Text entry depends on the phone’s active keyboard. Start with a short phrase and check the result. For Chinese through the CLI, enable the phone’s Pinyin keyboard and select the intended candidate.

Can I charge the phone while the board is connected?

The board occupies the iPhone’s USB port and draws power from the phone. This setup does not provide simultaneous wired charging. If your phone cannot charge wirelessly, take that into account before planning a long run. See the charging discussion.

Where do screenshots and tasks go?

Handsy sends screenshots to the AI service you choose so it can decide the next action. Read the privacy policy for what is sent, how it is stored, and your choices. You can replay and export run history on the phone. If you use your own API key, it is stored in the iOS Keychain.

With the CLI, screenshots and history are saved on your computer. Your computer agent may send screenshots to its chosen model provider. Check that agent’s permissions and data policy; the phone app’s free AI service does not supply the computer agent’s model.