Prepare the phone

Use a dedicated iPhone for PhysiClaw. It doesn’t need to be a flagship or the latest model. A cheap second-hand iPhone is perfectly fine.

PhysiClaw will have full control of this iPhone

We’ve done our best to make the agent protect your privacy, run reliably, and resist attacks, but please still make sure to:

• Sign out of Apple ID, so it can’t reach your iCloud photos, contacts, or Find My.
• Don’t tie this phone’s number to your important accounts. Otherwise controlling the phone is nearly enough to reset those accounts.
• Never give the agent the password to any account.
• Only install the apps you want PhysiClaw to use.
• Keep sensitive apps off it: no banking apps, no payment or wallet apps, no password managers.
• If you truly need payments, enable small-amount, password-free payments and keep only a small balance in that account, so any loss stays within an acceptable range.

Set up your IM app

PhysiClaw talks to you through instant messaging.

Add your contact

Sign in to your messaging app (e.g. WhatsApp) on the phone and start a chat with your own account. This is the thread PhysiClaw will use to reach you. Pin the conversation to the top of the chat list so it’s always in the same place.

Pin the app to the Dock

Drag the app icon to the Dock. That way, no matter which screen you’re on, PhysiClaw can always find and open it quickly.

Tip

This app is PhysiClaw’s only channel for reaching you. Keeping the icon and the conversation in fixed spots is what lets it check and reply to messages reliably.

Set up the Shortcuts

Same WiFi / LAN

Connect the iPhone and the computer running PhysiClaw to the same WiFi. The Shortcuts talk to the computer over the local network.

First, get the host name of the computer running PhysiClaw:

macOS

bash

scutil --get LocalHostName

Windows

powershell

hostname

Linux

bash

hostname

With the host name, the phone bridge address is <hostname>.local:8049 (the control port + 1). You can also reach it by the computer’s LAN IP (e.g. 192.168.1.20:8049), but the IP is assigned dynamically by DHCP and may change after a reboot, so .local is preferred.

If .local doesn’t resolve

.local relies on mDNS (built in on macOS). If the iPhone still can’t connect, use the LAN IP instead.

Tip

Replace every <hostname> below with your own host name.

Take a screenshot

Capture the current screen to Photos, for Upload the latest screenshot to send.

1. In the Shortcuts app, tap + to create a new one.

2. Add Take Screenshot.

3. Rename it to PhysiClaw Take Screenshot.

Upload the latest screenshot

Used when the camera’s view isn’t sharp enough and the agent needs a higher-resolution image.

1. In the Shortcuts app, tap + to create a new one.

2. Add Get Latest Screenshots.

3. Add Get Contents of URL:

   • URL: http://<hostname>.local:8049/api/bridge/screenshot
   • Show More → Method POST, Request Body File, File → the Latest Screenshots variable

4. Rename it to PhysiClaw Upload Screenshot.

Copy to clipboard

The agent sends text to the phone’s clipboard and pastes it. That’s faster and more reliable than tapping it out key by key with the stylus.

1. In the Shortcuts app, tap + to create a new one.

2. Add Get Contents of URL, with URL http://<hostname>.local:8049/api/bridge/clipboard and Method GET.

3. Add Copy to Clipboard, with its input set to the previous step’s Contents of URL.

4. Rename it to PhysiClaw Clipboard.

Turn on AssistiveTouch

AssistiveTouch is the floating on-screen button in iOS. The arm taps it to fire a Shortcut. Turn it on, then map the three gestures to the three Shortcuts.

1. Settings → Accessibility → Touch → AssistiveTouch → turn it on.

2. Under Custom Actions, set:

   • Single-Tap → PhysiClaw Take Screenshot
   • Double-Tap → PhysiClaw Upload Screenshot
   • Long Press → PhysiClaw Clipboard

Set the passcode

PhysiClaw can unlock the phone itself, but it only ever uses one fixed passcode: 111111. A dedicated passcode keeps your usual passcode from leaking through logs or config files. Set this phone’s passcode to 111111:

Settings → Face ID & Passcode → Turn Passcode On → enter 111111

Or turn off auto-lock

Turn off auto-lock instead (Settings → Display & Brightness → Auto-Lock → Never) and keep the phone unlocked. The trade-off is faster screen wear from an always-on display.

Fix the screen brightness

The camera tunes its exposure time to the screen’s brightness. Auto-Brightness can leave the camera’s view over- or under-exposed. Turn it off and set a fixed brightness of 50% or higher.

Settings → Accessibility → Display & Text Size → Auto-Brightness → off

Allow pasting from other apps

PhysiClaw uses Shortcuts to copy text to the clipboard and paste it into WhatsApp to talk with you, or into Amazon and Walmart to search for products. If a prompt asks you to confirm pasting every time, adjust this setting to skip it:

Settings → [App Name] → Paste from Other Apps → Allow