Remote coding agents

Let a coding agent on another machine build and update one app on your phone, while your Mac keeps its signing certificates and paired-device access. You approve the first installation, then give the agent a private global update URL for that app on that device.

Prepare the two machines

Set up ipa-hub and App Manager on your Mac and pair your phone. Keep the Mac awake, the server running, and the phone available over USB or the network.

The agent's machine needs to produce a developer .ipa for your device and host it at a stable HTTP URL, for example:

http://build-machine.local:8080/MyApp.ipa

Your Mac must be able to download that URL, and the agent must be able to reach your Mac's ipa-hub port, normally 19464. They can be on the same LAN or connected through a private VPN such as Tailscale. The phone does not need to download the IPA directly; ipa-hub does that on the Mac.

For a build server on a private network, allow its exact hostname or IP when starting ipa-hub:

ipa-hub serve --allow-host build-machine.local

--allow-host also works with ipa-hub service install when configuring a globally installed background service. Supply the hostname or IP used in the artifact URL, without a scheme or port. This permits downloads from that trusted host; it does not grant the build machine device-management access.

Install the first build yourself

  1. Ask the agent to build the IPA, host it, and give you its download URL.
  2. On your phone, open ipa-hub from the Home Screen. Alternatively, on the Mac running ipa-hub, open http://localhost:19464 and select your phone. This browser administration shortcut works only on the host Mac; opening the server from another computer does not grant that access.
  3. Paste the agent's IPA URL into the install input. Select a signing team if prompted, click Install app, and confirm that you trust the publisher.
  4. Wait for installation to finish. In that app's entry, open ••• → Get global update URL, copy the URL, and give it to your coding agent.

Copy the global update URL from the menu, rather than an embedded IPAHub.updateURL. Newly issued global links authorize another machine to update that one tracked app on that one device. Links created before this capability was added retain their previous restrictions; use the menu again to issue a new link.

Build and install on demand

When you ask for another build, the agent replaces the IPA at the same download URL and calls your global update link. ipa-hub checks the saved source, downloads the changed file, signs it on your Mac, and installs it on the same phone.

Use POST with ?install=foreground to wait for completion and receive progress:

curl --fail-with-body --no-buffer --request POST \
  'http://your-mac.local:19464/global-update/<installation-id>?install=foreground'

Replace the example with the link you copied. If the agent cannot resolve your Mac's .local hostname, use the Mac's reachable LAN or VPN IP, preserving the port and the complete /global-update/<installation-id> path. A global update link does not provide an Internet relay. Keep the HTTP connection on a trusted LAN or private VPN.

An available update returns newline-delimited JSON progress followed by a result event. An error or selection event needs attention; HTTP 200 alone does not mean installation succeeded. If no update is detected, the endpoint returns ordinary JSON with installing: false; inspect its reason when present. See the global update endpoint contract for all response details.

The agent can repeat this whenever you ask it to build and install. You do not need to paste the IPA URL or approve another new-app installation each time. Adding &open=false prevents reopening the app. Otherwise, ipa-hub reopens it only if it was running immediately before installation.

Publish updates reliably

Keep the app's original bundle identifier and target device platform unchanged. Publish each completed IPA atomically so a download cannot read a partially written build.

The artifact server should support GET and HEAD, and return a fresh ETag or Last-Modified value when the file changes. A content-based ETag is the most reliable choice, including for builds with identical file sizes or builds published within the same second. Handle conditional requests correctly: return 304 only when the served file has not changed. A different app version string alone cannot tell ipa-hub that a remote file changed without downloading it.

If a foreground request disconnects during checking or downloading, ipa-hub cancels that work. Once extraction, signing, or installation has begun, it finishes independently. Check the app's status in App Manager before retrying an interrupted installation.

Instructions to give your agent

Copy this along with the IPA URL and the private global update URL:

Build a developer IPA for my device and publish it at the fixed artifact URL. Keep its bundle identifier and platform unchanged, replace the file atomically, and make sure the HTTP server updates its ETag or Last-Modified headers. When I ask you to build and install, publish the completed IPA and POST to the global update URL with install=foreground. Read the progress stream through its final result; report error or selection events instead of treating HTTP 200 as success. If the request disconnects, report the result as unconfirmed and let me check App Manager before retrying. Keep the update URL private. You do not need my Apple account, signing certificates, App Manager enrollment credentials, or general device access.

Anyone holding the link can check for and trigger updates of its app on its device, using the source and signing choices already saved on the Mac. Request parameters cannot substitute another source, app, or device. The link does not authorize new-app installations, listing other apps or devices, manager enrollment, or permission changes. The agent cannot use it as a credential for other API routes.

To revoke the link, remove server/update-links/<installation-id>.json under your ipa-hub data directory on the Mac (~/.ipa-hub by default). A later Get global update URL action creates a new secret. Revocation blocks future requests; it does not cancel an installation already underway.

Edit this page