For anyone who has made an app with shipvo init and wants to see it on a phone-shaped screen in seconds, without installing Android Studio, Xcode or Playwright. You will get a simulated Android or iPhone in a browser tab. Your AI assistant can drive the same phone while you watch.
ⓘ Copyright credits
Music: "Princess of my heart" by Zero-project (Jamendo, CC BY 3.0). Source: https://www.jamendo.com/track/633200Start here (no technical background needed)
You need the app folder from Build your first app and a terminal open in it. A terminal is a window where you type commands (see the glossary).
Type this and press Enter:
npx shipvo run androidUse
iosinstead ofandroidfor an iPhone-style phone.Wait while Shipvo builds a web copy of your app. It does not need an account or a phone.
Your browser opens on a page with a phone in the middle, in its Android or iPhone frame.
Click around in the phone like you would tap. When you are done, go back to the terminal and press Ctrl+C.
If it fails:
- The terminal says it cannot build for web and names a file: the named file uses something that only works on a real phone. Ask your assistant to fix that file.
- The terminal says the port is in use: run
npx shipvo run android --port 4600(any free number works). - A message about
@shipvo/sim: your app is older than this feature. Runnpm install --save-dev @shipvo/simand try again.
What you get
| Android | iOS | |
|---|---|---|
| Phone size | 412x915 | 393x852 |
| Look | Punch-hole camera, gesture bar | Dynamic Island, home indicator |
| System sheet | "Show Android system sheet" button | "Show iOS system sheet" button |
The page scales the phone to your window. Add ?dark=1 to the address to see the dark frame.
How fast it starts
CI times shipvo run android and shipvo run ios on a clean machine with only Node: a fresh shipvo init app, its install finished, then shipvo run <platform> --no-open. The clock starts when the process is spawned and stops when the first tap on the phone page has been done. Install time is not in the numbers.
Measured on 2026-11-07 on a GitHub-hosted ubuntu-latest runner:
| step | Android (seconds since start) | iOS (seconds since start) |
|---|---|---|
| start (process spawned) | 0.00 | 0.00 |
| server listening | 8.99 | 8.81 |
| phone page ready (app loaded) | 10.42 | 9.88 |
| first tap done | 10.73 | 10.19 |
Run: CI run 42355471525 (job shipvo run android (time to first tap), artifact run-time). The script is scripts/first-run/run-time.mjs.
Apps with a router or a base path
An app that uses expo-router or React Navigation opens on its own first screen: shipvo run sees the router in package.json and gives the app its own addresses, so /feed/1 is /feed/1 and a reload stays on that screen. An app built with Expo's experiments.baseUrl (for example /static) gets its files under that path.
Edit and save, the phone updates
While shipvo run is open it watches your project. When you save a file, it rebuilds the web copy in the background and reloads the app inside the phone. You stay on the same screen address. The terminal prints one line per rebuild, for example rebuilt in 2.1 s. Rebuilds after a save keep the Metro cache, so they are faster than the first build, which starts clean. As soon as a save is seen, the terminal prints Rebuilding... and the page shows a small "Updating…" hint until the new build loads.
If a rebuild fails (a typo in your code, say), the phone keeps your last good version. The terminal prints the error, and a small red bar under the phone shows it too. Save a fix and the bar goes away and the phone reloads.
The tests in packages/cli/test/run-live-reload.test.ts edit a fixture app and check the Android and iOS frames in Chromium, and they print the save-to-visible time for each.
The device panel
Next to the phone, on both the Android and iOS frames, the page has a collapsible Device panel. Each control sets the simulated device state your app reads, and writes a line to the event log on the page, marked "(simulated)".
- Location: pick Douala, Paris, New York or Nairobi, or type a latitude and longitude.
- Camera: pick a test image. The app's file and photo picker offers it.
- Biometrics: succeed, fail or not enrolled.
- Payment: succeed, cancel or decline.
- Network: online, offline, 2G or slow 4G, using the profiles from
@shipvo/sim. - Push: send a test notification with a title and message.
packages/cli/test/run-panel.test.ts clicks every control on the Android and iOS frames and checks what the app reads.
Your app reaches its backend, with no CORS errors
On Android and iOS, an app calls its backend directly and there is no CORS. In the simulated phone the app runs in a browser tab, so Shipvo sends every request to another origin (fetch and XMLHttpRequest) through the shipvo run server at /__shipvo/net. The server makes the real request from Node and returns the status, headers and body unchanged. Requests to the app's own origin go straight through.
- Every method, request bodies, binary data and streaming responses work. A streamed response arrives in chunks.
http://localhost:<port>and backends on your network work, andhttpbackends work from the page.- Each phone session has one cookie jar, kept by the server, the way each installed app has its own cookies. Two browser tabs have two jars.
- The phone's network profile (offline, 2g, 3g, slow-4g, spotty) applies to these requests too.
- The route is added to pages you open on your own computer. Only that page can use it, with its session token, on the loopback address. A phone you open with
--lanand the QR code calls your backend directly, as it does on a real network. - A request the network profile fails ends in the same network error on
fetchandXMLHttpRequest. Every proxied request is added to the device log with its method, host, status and time.
Let your assistant drive the phone you are watching
While shipvo run is up, it writes .shipvo/run.json in your project (port, platform, app, a secret session token and the process id) and adds .shipvo/ to .gitignore. The token only works from your own computer.
When an assistant calls the Shipvo MCP tool open_app for the same app, it finds that file and drives your live phone. The result says attached to the live shipvo run phone. If no live phone is found, it says headless session and uses its own hidden phone. Attached sessions support screen, tap, type, scroll and back; other tools return not_supported_attached with the next step: open the app again with attach: "never" and watch it at /watch. Attaching needs Node 22 or newer. Full tool list: Agents.
The assistant sees the same list of buttons and text as in the simulator, with [ref=eN] numbers it can tap. Refs are numbered differently from the simulator's, and a ref from an earlier page returns stale_ref so it never taps the wrong thing.
Options
shipvo run android|ios [--no-open] [--port <n>] [--native] [--lan]| Option | What it does |
|---|---|
--no-open | Print the address and do not open a browser. |
--port <n> | Use port n, 0 to 65535. Default: any free port. |
--lan | Also serve the phone on your Wi-Fi. Prints a URL with a random token (?t=...) and a QR code. On a phone browser the app fills the screen with no frame; on a desktop browser the frame stays. Every request needs the token, otherwise the answer is 403. Anyone on the network who has the address can open the page. Plain HTTP; no camera or sensors from the phone. |
--native | Run on a real emulator or simulator with npx expo run:android or run:ios instead. Needs Android Studio or Xcode. |
Troubleshooting
| You see | Why | Fix |
|---|---|---|
Port 4600 is in use. Pass another --port <n>. | Another program uses that port. | Choose another number. |
--port needs a number from 0 to 65535 | The value is not a port. | Use digits only. |
Unknown argument | A flag is mistyped. | The message shows the usage line. |
Assistant says headless session | shipvo run is not running in that project, or the app name differs. | Start shipvo run in the project, then call open_app again. Pass attach: "always" to get an error instead of a fallback. |
no_live_run | You passed attach: "always" and no shipvo run is live. | Start shipvo run in the project, then call open_app again. |
attach_failed with "attach needs Node 22+" | Old Node. | Install Node 22. |