Get started

OTA updates on the phone

Publish a release, watch it land on the simulated Android or iOS phone, apply it and see a bad one roll back.

Edit on GitHub

This page is for developers and for assistants testing updates. You get the update states, the three tools, and a runnable test of publish, apply and roll back on the simulated phone.

Publish a release, watch it land on the simulated phone, apply it, and see a bad one roll back. No device needed. Everything here is simulated: nothing real is installed, and device_log marks each step simulated.

What the phone shows

get_update_state returns one of:

StateMeaning
idleNothing in progress
checkingReading the release pointer
downloadingFetching the bundle
readyA verified newer release is held, not yet running
appliedThe phone restarted on the new release
revertedThe new release failed 3 boots and the phone went back

It also returns the running release, the held pending_release, the last reason (verify_failed, download_failed, crash_loop) and a list of blocked releases. For ready, applied and reverted the phone shows a status banner that starts with "Simulated". It is in the accessibility tree, in both skins.

Tools

ToolWhat it doesTyped errors
get_update_stateReads the statenone
check_for_updateFetches and checks the latest release. Ends in ready, or idle with verify_failed or download_failedno_update
apply_updateRestarts the app on the held releasenot_ready

A bad signature or a hash mismatch is not an error result: the state is idle with reason verify_failed, and apply_update then fails with not_ready. The release is never applied. no_update also means no update source is set.

Update source

Start the simulator with the update source and the app's public key (from shipvo.json):

bash
shipvo-sim --update-url http://127.0.0.1:8099 --update-key <public key, base64>

The same values can come from PN_UPDATE_URL and PN_UPDATE_KEY. The source must serve:

  • GET /pointer.json: a release pointer signed with the app's ed25519 key. The simulator checks the signature over the canonical JSON (sorted keys, no whitespace, no signature field), the same way the runtime does.
  • The bundle at <web.base>/<web.entry>, whose sha256 equals web.sha256 in the pointer.

Crash loop

After apply_update a new release has to boot without a page error. After 3 failed boots in a row, the phone drops the release, blocks it, runs the old release again and reports reverted with reason crash_loop. This is the same rule as in spike results. A boot with no page error confirms the release. Only page errors seen while the page loads count: a crash after the page is idle does not count as a failed boot. A blocked release is not offered again.

Run it

packages/sim/update-live.test.mjs is a runnable version of this page. It starts the simulator against a local stub, publishes release 2, then walks check_for_update and apply_update:

bash
pnpm --filter @shipvo/sim exec node --test update-live.test.mjs

The simulator runs web bundles (one index.html). In shipvo run, the frame page draws the banner from a pn:update message.

The simulator refuses a signed release that is not newer than every release the session knows: the running one (13 and r13 both count as 13), the previous one, ones it ran before and blocked ones. This stops an old signed release being replayed. If the app has no release number and the session has seen none, any validly signed release counts as new.

Troubleshooting

You seeWhyFix
check_for_update fails with no_updateNo newer release exists, or no update source is setStart the simulator with --update-url and --update-key, then publish a newer release
State is idle with reason verify_failedThe signature or the bundle hash does not matchCheck that --update-key is the public key from shipvo.json, then publish again
State is idle with reason download_failedThe source did not serve the bundle at <web.base>/<web.entry>Open that URL in a browser and fix the path in the pointer
apply_update fails with not_readyNothing is held. A check has not ended in readyRun check_for_update first and read the state
A release you published is not offeredIt is not newer than every release the session knows, or it is blockedPublish a higher release number
State is reverted with reason crash_loopThe release raised a page error on 3 boots in a rowFix the page error and publish a new release. The blocked one is not offered again

Next steps

  • CLI guide: publish, promote and roll back real releases.
  • Agents: every MCP tool, including the update tools.
  • Spike results: the measured crash-loop rule.