ios-sim-recorder-agent
v0.2.0
Published
Local agent for the OnDemand iOS Simulator Recorder plugin — records an iOS Simulator on your Mac and returns a video link.
Maintainers
Readme
iOS Simulator Recorder — local agent
Records an iOS Simulator on your Mac from the OnDemand Playground, and hands back a playable video link.
Playground → broker.on-demand.io → this agent (your Mac) → xcrun simctl
↓
Cloudinary ← upload → URL back to the PlaygroundThe agent dials out to the broker, so nothing needs to reach into your machine — no port forwarding, no tunnel, no exposed server.
Setup
npx ios-sim-recorder-agentFirst run asks four questions and saves the answers to
~/.config/ios-sim-recorder/config.json (mode 0600). After that the same
command just connects.
You need OnDemand MQTT credentials: app.on-demand.io → API Keys Management → IoT(MQTT) credentials → create mqtt password. Your username there is your companyId; the password is shown once.
Cloudinary is optional. Without it recordings still work — they stay on your Mac
and stop returns the local path instead of a URL.
npx ios-sim-recorder-agent doctor # check this Mac can do the job
npx ios-sim-recorder-agent setup # re-enter credentialsLeave it running while you use the plugin. Ctrl-C stops it, and stops any recording in progress.
Requirements
macOS with Xcode and at least one iOS Simulator runtime, plus Node 20+.
No idb, no baguette, no Apple Silicon requirement — this drives
xcrun simctl directly and works on Intel Macs.
Using it
In the Playground, with the agent running:
Start recording the iPhone 16 Pro on iOS 18.2
…drive the simulator…
Stop recording
stop answers immediately and the video is processed in the background, so the
agent then asks for the link — usually in the same breath. If it says the
recording is still processing, ask again in a moment.
Long recordings
A four-minute session produces roughly 290 MiB, well over Cloudinary's 100 MiB
limit. Recordings above 80 MiB are therefore compressed with avconvert
(Preset1280x720, giving 588x1280) before upload. Measured at 6.6x on a
90 MiB capture, so a heavy 290 MiB four-minute recording lands around 44 MiB. avconvert ships with macOS, so there is nothing to install; if it is
somehow missing the original is uploaded and the size limit reported honestly.
Smaller recordings are uploaded untouched, because Cloudinary compresses better and keeps full resolution — a 13.65 MiB capture came back as 0.65 MiB at 1206x2622. Compression costs resolution and only earns its place when a recording would otherwise be rejected.
doctor reports whether compression is available.
Updating the plugin after a change
The agent and the OnDemand plugin have to agree on the topic list. A code change alone does nothing until the schema in the Playground is updated.
- Playground → Plugins → iOS Simulator Recorder → edit
- MQTT schema tab → replace the whole thing with
plugin-schema.json - Save
- Restart the agent so it subscribes to any new topics
The current schema has three topics:
| topic | operation |
| --- | --- |
| /simulator/recording/start | startSimulatorRecording |
| /simulator/recording/stop | stopSimulatorRecording |
| /simulator/recording/status | getRecordingStatus |
Suggested conversation starters:
Start recording the simulatorStop recording and send me the video
Testing it end to end
Start the agent and leave that terminal alone — typing in it kills the agent mid-test:
node --env-file=.env bin/cli.mjsCheck first that only one agent is running. Two agents subscribed to the same topics both answer every command, which makes the results unreadable:
pgrep -fl 'bin/cli.mjs'Short recording
In the Playground:
Start recording
…do something in the simulator for ten seconds…
Stop recording
In the agent log you should see, in order:
← .../start data has no device_name when you did not name one
→ .../response state: active, with a recording_id
← .../stop
→ .../response state: processing ← under a second
← .../status
→ .../response state: ready, with a url ← usually the first pollThen open the URL. It should be an .mp4 that plays in the browser.
Long recording — the case this was built for
Start recording
…drive the simulator for four minutes…
Stop recording
stop still answers in about a second. Processing then takes a minute or two,
so get_recording will report processing once or twice before returning the
URL. That is expected — the agent log shows compressing NNN MiB then
compressed to NN MiB, uploading.
If the model stops polling and tells you it is still processing, just ask:
Is my recording ready?
The work completes in the background either way; polling only affects when you see the link.
What to check afterwards
ls -la ~/Library/Application\ Support/RemoteSimulatorAgent/artifacts/The original recording stays on disk. Only the compressed copy is deleted after a successful upload.
Can other people use this?
Yes. MQTT topics are scoped by companyId, which is also the MQTT username, so each person's agent only ever receives their own organisation's commands. Nothing in the agent is specific to one account — it all comes from config.
Each user needs their own MQTT credentials, their own Cloudinary account (or none), and their own running agent.
Environment variables
These override the saved config, which is handy in CI or for development:
| Variable | Purpose |
| --- | --- |
| ONDEMAND_COMPANY_ID | companyId, also the MQTT username |
| ONDEMAND_MQTT_PASSWORD | from IoT(MQTT) credentials |
| CLOUDINARY_CLOUD_NAME / CLOUDINARY_API_KEY / CLOUDINARY_API_SECRET | upload target |
| SIM_DEVICE_NAME | default simulator, e.g. iPhone 16 Pro |
| SIM_RUNTIME | default iOS version, breaks ties between same-named devices |
| LISTEN_ON_ACTIONS | 1 to also listen on /actions |
Commands
For users
npx ios-sim-recorder-agent # connect and wait for commands
npx ios-sim-recorder-agent doctor # check this Mac can do the job
npx ios-sim-recorder-agent setup # re-enter credentials
npx ios-sim-recorder-agent --help # all options
npx ios-sim-recorder-agent@latest # force the newest published versionLeave the first one running while you use the plugin. Ctrl-C stops it, and stops any recording in progress.
Working on the code
git clone <repo> && cd sim-recorder-plugin
npm install
cp .env.example .env # then fill in the credentialsnpm test # no broker, credentials or simulator needed
node --env-file=.env bin/cli.mjs # run the agent from this checkout
node --env-file=.env bin/cli.mjs doctorThree device-selection checks only run when exactly one simulator is booted, so the assertion count varies with the state of the machine.
agent.mjs is a module, not an entry point — run bin/cli.mjs.
Poking at the simulator directly
node cli.mjs devices # list simulators, flags ambiguous names
node cli.mjs resolve "iPhone 16 Pro" # see how a name resolves
node cli.mjs smoke "iPhone 16 Pro" --runtime "iOS 18.2" --seconds 10
node cli.mjs status # in-flight recordingscli.mjs start and cli.mjs stop as separate commands will not find each
other — active recordings live in memory, so both must happen in one process.
Use smoke, or the agent, which is long-running.
Releasing
npm test # must be green
npm pack --dry-run # check what would ship
npm version patch # or minor / major
npm publish # prompts for 2FAThen verify what a new user actually gets, from the registry rather than this checkout:
cd /tmp && npx ios-sim-recorder-agent@latest doctorUseful while debugging
xcrun simctl list devices available # what is installed
xcrun simctl list devices booted # what is running
xcrun simctl boot "<udid>" # boot one by hand
xcrun simctl shutdown all # stop them all
pkill -f 'bin/cli.mjs' # stop every running agent
ls -la ~/Library/Application\ Support/RemoteSimulatorAgent/artifacts/
ffprobe -v error -show_entries format=duration,size \
-show_entries stream=codec_name,profile <file.mp4>Two agents subscribed to the same topics will both answer every command, which
makes the results unreadable. Check with pgrep -fl 'bin/cli.mjs' before
starting one.
| File | |
| --- | --- |
| bin/cli.mjs | Command line: run, setup, doctor |
| config.mjs | Config file and interactive setup |
| defaults.mjs | Cloudinary credentials shipped with the package |
| agent.mjs | Broker connection, subscribe, dispatch, reply |
| routes.mjs | Maps an MQTT envelope onto an action, builds the reply |
| recorder.mjs | Start/stop via simctl. Watchdog, disk guard, sandbox |
| upload.mjs | Cloudinary upload, signed or unsigned preset |
| plugin-schema.json | The MQTT schema to paste into the OnDemand plugin |
| PENDING.md | Known gaps and what to do about them |
| probe-media-api.mjs | Evidence that OnDemand's Media API cannot host these files |
Recordings are written to
~/Library/Application Support/RemoteSimulatorAgent/artifacts/.
Things worth knowing
Recordings are capped at 100 MB, which in practice bites long before the
15-minute ceiling. Measured rates: static screen ~50 KB/s, light use ~390 KB/s,
heavy app switching ~700 KB/s, and one real session hit 1 MB/s — 118 MB in 100
seconds. Past the cap stop returns ARTIFACT_TOO_LARGE and the recording stays
safely on disk.
simctl records variable frame rate. It only writes a frame when the screen
changes, so the file's own duration drifts against wall clock — 12 seconds of a
motionless screen produced 0.07 s of video. The duration_ms in the reply is
accurate wall clock; the container's number is not.
simctl writes QuickTime, not MP4. The upload asks Cloudinary for
format: mp4, which remuxes on the way in — otherwise the URL is a .mov that
Safari plays and Chrome often won't.
OnDemand's Media API is not file storage. It requires a plugins array
naming a plugin that can process the upload, and rate-limits per minute. That is
why uploads go to Cloudinary. probe-media-api.mjs reproduces it.
Port 1883 is plaintext. OnDemand documents no TLS port for the broker, so commands and the returned URL travel unencrypted.
A failed upload is not a failed recording. stop returns
partially_succeeded with the local path and the error, rather than telling you
the recording was lost when it is safe on disk.
An already-booted simulator wins. If you have one open, that is what gets
recorded — the configured default only applies when nothing is running, and an
explicitly named device_name overrides both. This avoids booting a second
simulator you cannot see while the one you are using sits there.
Device names are ambiguous. iPhone 16 Pro exists once per installed iOS
runtime. Without a runtime, start returns SIMULATOR_AMBIGUOUS listing the
candidates instead of guessing. Asking for a device on a runtime it is not
installed on gives NO_SIMULATOR_MATCH naming the runtimes it does exist on.
doctor warns about the ambiguity up front.
Cold starts take ~50 seconds. If the simulator isn't booted the agent boots it first; measured at 47 s. Whether OnDemand's reply window tolerates that is untested — a 27 s start has succeeded.
