Build and install the iOS app

The current agent runs inside ESP32 Agent, an app you build and install on your iPhone. A Mac with Xcode is part of initial setup, even though a computer is not needed during a run.

Configure your local build

From the project root:

cp ios/Config/Local.xcconfig.example ios/Config/Local.xcconfig

Open ios/Config/Local.xcconfig in an editor. Set your own signing team and a unique bundle identifier:

DEVELOPMENT_TEAM = YOUR_TEAM_ID
IA_BUNDLE_ID = com.yourname.esp32agent

Replace both example values. The widget identifier and App Group are derived from your app’s bundle identifier. Keep this local configuration private, especially if you add model credentials.

Free Apple ID and optional entitlements

A free Apple ID can sign a development build. Its signature expires after seven days, so re-sign and install again when needed.

The example configuration opts into entitlement files. If your signing team cannot provision the optional capabilities, use the opt-out supported by that file:

IA_ENTITLEMENTS =
IA_WIDGET_ENTITLEMENTS =

This removes those optional entitlement files from your local build. One-tap hotspot joining requires Hotspot Configuration and a paid developer account. Without it, join the hotspot manually using the credentials shown in the app. Optional App Group and notification features may also be unavailable in a build without their entitlements.

Do not fix a signing error by inventing an entitlement or copying someone else’s team identifier. Check Xcode’s Signing & Capabilities messages against your own account.

Build on the phone

open ios/IPhoneAgent.xcodeproj

1. Connect your iPhone to the Mac and trust the computer if prompted.
2. Select the IPhoneAgent scheme and the physical iPhone as the destination.
3. Confirm the signing team and bundle identifiers in Xcode.
4. Build and run the app. Follow any development-app trust or Developer Mode prompts from your installed iOS and Xcode versions.

The deployment target is iOS 18.0. A simulator can help with app UI development, but it does not replace the physical iPhone and board for this workflow.

Regenerate the project when needed

The Xcode project is generated from ios/project.yml using XcodeGen. If you change that project definition, regenerate from the ios directory:

cd ios
xcodegen

For an unmodified checkout with the project already present, start by opening the existing project.

Finish setup

Launch ESP32 Agent and move the board from the Mac to the iPhone. Continue with Bluetooth, mirroring, and pointer setup.

The project currently uses a private suspend API to leave its own app. These instructions cover a self-built development app; they do not imply an App Store release.