Skip to content
Skills Library
Programming · Automation

simctlhouse

/simctlhouse

Get an exclusive iOS simulator (iPhone or iPad) for building, testing or running an app, and give it back when done. Use whenever you are about to run `xcodebuild test`/`build` or `xcrun simctl` against a simulator, need a simulator destination or UDID, or choose a simulator, so parallel agents never share or fight over one. Use it instead of picking a simulator from `xcrun simctl list`, using "booted", or using `-destination 'name=iPhone ...'`.

Repository
simctlhouse ↗
Licence
MIT
Last repository change
06.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 06.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Get an exclusive iOS simulator (iPhone or iPad) for building, testing or running an app, and give it back when done. Use whenever you are about to run `xcodebuild test`/`build` or `xcrun simctl` against a simulator, need a simulator destination or UDID, or choose a simulator, so parallel agents never share or fight over one. Use it instead of picking a simulator from `xcrun simctl list`, using "booted", or using `-destination 'name=iPhone ...'`.

Triggers from the description

bootedname=iPhone ...
Original author description

Get an exclusive iOS simulator (iPhone or iPad) for building, testing or running an app, and give it back when done. Use whenever you are about to run `xcodebuild test`/`build` or `xcrun simctl` against a simulator, need a simulator destination or UDID, or choose a simulator, so parallel agents never share or fight over one. Use it instead of picking a simulator from `xcrun simctl list`, using "booted", or using `-destination 'name=iPhone ...'`.

How it works

  1. One command: simctlhouse run
  2. Several steps: acquire and release
  3. Rules
  4. Exit codes
  5. Looking around
Original SKILL.md headings · 114 lines, 1,203 words
SKILL.md preview
---
name: simctlhouse
description: Get an exclusive iOS simulator (iPhone or iPad) for building, testing or running an app, and give it back when done. Use whenever you are about to run `xcodebuild test`/`build` or `xcrun simctl` against a simulator, need a simulator destination or UDID, or choose a simulator, so parallel agents never share or fight over one. Use it instead of picking a simulator from `xcrun simctl list`, using "booted", or using `-destination 'name=iPhone ...'`.
---

# simctlhouse: exclusive simulators for agents

Other agents use this machine's simulators at the same time.
A simulator you pick yourself (by name, `booted`, or from `simctl list`) collides with theirs and fails at random.
Always get your device from simctlhouse, in one of two ways:

- One command does the whole job, such as an end-to-end `xcodebuild test`: wrap it in `simctlhouse run`.
- Several steps must happen on the same device, such as install, launch and screenshot: hold it with `acquire` and `release`.
  Two `run`s may get two different devices, so never split such steps across `run`s, and do not chain them into one `run` with `sh -c`.

## One command: `simctlhouse run`

```sh
simctlhouse run --holder "<short task label>" -- xcodebuild test -scheme App
```

It leases a device, boots it (unless you pass `--skip-boot`), runs the command, and releases the device when the command exits, also when it fails, is interrupted or is killed.
The lease lasts as long as the command, so there is nothing to renew.

- xcodebuild gets `-destination id=<UDID>` added.
  Do not pass a simulator `-destination` yourself: one naming another simulator (`name=...`, `booted`) is refused with exit code 125.
  `generic/platform=iOS Simulator` is fine.
- Any other command gets the device through `{udid}` and `{name}` in its arguments, or `$SIMCTLHOUSE_UDID` and `$SIMCTLHOUSE_DEVICE_NAME`:

  ```sh
  simctlhouse run -- ./scripts/ui-tests.sh {udid}
  ```

- Device options are those of `acquire` (below): `--family`, `--model`, `--os`, or a device name or UDID.
- `--count N` leases N devices; xcodebuild then tests on all of them at once (add `-parallelize-tests-among-destinations` to split the tests instead).
  Other commands name each device with `{udid0}` to `{udid<N-1>}` (`{udid}` is refused then), or read `$SIMCTLHOUSE_UDID_0` to `$SIMCTLHOUSE_UDID_<N-1>`.
- `--timeout SECONDS` stops the command after that long, with exit code 124.
- `--skip-boot` skips the boot when the command needs no running simulator (`xcodebuild build`, `build-for-testing`).
- stdout is the command's own; simctlhouse's messages go to stderr, prefixed with `simctlhouse:`.
- If your shell tool times out sooner than the command may take, run it in the background rather than under that timeout.

## Several steps: `acquire` and `release`

1. Acquire a device. stdout is just the UDID; progress messages go to stderr.

   ```sh
   UDID=$(simctlhouse acquire --holder "<short task label>")
   ```

   Options: `--family ipad` (default `iphone`), `--model "iPhone 17 Pro"` (exact name from `xcrun simctl list devicetypes`), `--os 26` or `--os 26.5`.
   Defaults are the latest iPhone Pro or iPad Pro 11-inch on the newest installed iOS.
   The device is booted when the command returns: at once for a free device, after about 30s when one has to be created.
   If you only build (`xcodebuild build`, `build-for-testing`) and need no running simulator, add `--skip-boot` to skip that wait.
   To get a specific device back (say, one where your app is already installed), pass its name or UDID: `simctlhouse acquire <name|udid> --holder "..."`.

2. Use the UDID everywhere, never `booted` or a device name:

   ```sh
   xcodebuild test -scheme App -destination "id=$UDID"
   xcrun simctl install "$UDID" path/to/App.app
   xcrun simctl launch "$UDID" com.example.app
   ```

3. Release it as soon as you are done, also after failures:

   ```sh
   simctlhouse release "$UDID"
   ```

## Rules

- Always pass `--holder` with a label that says who you are and what you are doing; `list` and `history` show it to whoever investigates later.
- One lease per task: reuse your UDID for every build and test in it instead of acquiring again for each command.
- A lease from `acquire` expires 30 minutes (or `$SIMCTLHOUSE_LEASE_SECONDS`) after `acquire` returns or the last `renew`; `acquire` and `renew` print how long you have (`expiresAt` in `--json`).
  An expired device is re-created under a new name and handed to someone else, even in the middle of your build; its old name and UDID then fail with exit code 3.
  If your work may run longer, run `simctlhouse renew "$UDID"` before each long step, at the latest when two thirds of the lease have passed.
- Released devices stay booted for the next agent and are not erased.
  For a pristine device, release it, run `simctlhouse erase <name>`, and acquire again; or uninstall your app first.
- Never `xcrun simctl shutdown/erase/delete` a device yourself, and never touch simulators simctlhouse did not give you.
- A background daemon (`simctlhouse daemon serve`) enforces expiry and idle shutdown on time; commands start it and it exits on its own.
  Do not stop, kill or start it, and do not set `SIMCTLHOUSE_DAEMON`.
- Do not run `simctlhouse delete --unused`, `delete --all` or `simctlhouse uninstall` unless the user asks: other agents' devices are in the same pool.
- For retry-safe scripts, take the lease ID from `simctlhouse acquire --json` and pass it back: `simctlhouse release "$UDID" --lease-id "$LEASE_ID"`.

## Exit codes

`run` exits with its command's own code, or 128+N if signal N ended the command.
Its own failures use codes commands rarely do:

| Code | Meaning | What to do |
| --- | --- | --- |
| 124 | `--timeout` passed; the command was stopped | Raise the timeout, or find out why the command hangs |
| 125 | simctlhouse failed: no device (stderr says why, as for `acquire`), a refused `-destination`, invalid usage, or someone released or deleted the device mid-run | Read stderr; fix the command, or run it again |
| 126 | The command cannot be executed | Fix the command |
| 127 | The command was not found | Fix the command or `PATH` |

The other commands:

| Code | Meaning | What to do |
| --- | --- | --- |
| 1 | simctl failure, or no Xcode selected | Read stderr. If it says Xcode is needed, stop and tell the user; do not run `sudo xcode-select` yourself. Otherwise retry once, then report |
| 2 | Unknown model, or no runtime for that model/OS | Check `xcrun simctl list devicetypes` / `runtimes`, or drop `--model` / `--os` |
| 3 | Device not found | Your lease expired and the device was reclaimed. Acquire a new one; on `release` this is harmless |
| 4 | Lease ID mismatch / not leased | The device is no longer yours. Acquire a new one |
| 5 | Device leased, busy, or used by another process | Pick another device, or try again shortly; use `--force` only on a device you hold |
| 64 | Invalid usage or `SIMCTLHOUSE_*` value | Fix the command or the environment variable named in stderr |

## Looking around

Every command that takes a device accepts its name or its UDID.

- `simctlhouse list` shows each device's status, holder, and what happens next: when a lease expires or a free device shuts down (`--json` available).
  Filter like `simctl list devices`: `list booted`, `list available`, or a search term such as a name, UDID or holder.
- `simctlhouse udid <name>` prints the UDID of a device you know by name.
- `simctlhouse history [<name|udid>]` shows who held a device, when, and how each lease ended; use it when a device disappeared or misbehaved.
  Old names and UDIDs still resolve.
- `simctlhouse daemon status` shows whether the daemon runs; its log is `$(simctlhouse home)/daemon.log`.

Versions

The database has no other skills named simctlhouse.

Database snapshot: 13.11.2026 · package version 4ae123f61500 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ios-simulator-build
    Builds Release iOS simulator apps (clean prebuild, pinned Xcode, UDID-named simulator) and proves the .app. Use when smoke-testing on the iOS simulator, or xcodebuild, simctl or CocoaPods fails. Not for TestFlight (ios-release-testflight).
  • 86herdr-ios-simulator
    Build, run, drive and debug iOS apps on a simulator shared with the user inside herdr. Use whenever the user wants to run, see, test or debug an iOS or iPhone app ("run it on the simulator", "show me on the iPhone", "tap through the sign-in flow", "why does it crash", "check the…
  • 100duo-setup
    Sets up a Mac to build, run and test apps for iPhone Duo, the foldable iPhone with an outer display and an inner display, covering Xcode 27.1 next to an older Xcode with DEVELOPER_DIR (no sudo xcode-select), xcodebuild -version, the iOS 27.1 SDK and runtime, the iPhone Duo…
  • 95simulator-workflows
    iOS Simulator device and app management with simctl. Use when managing simulator devices (boot, create, delete), installing/launching apps, or troubleshooting simulator issues. Covers device lifecycle, app lifecycle, and diagnostics.
  • 100ios-android-logs
    Gets, filters, streams, and saves logs and crash reports from Capacitor apps on iOS Simulator, iPhone, Android emulator and devices. Explains where Capacitor output goes (iOS bridge and mirrored JS console lines are stdout-only, so missing from Console.app and `log stream`;…
  • 100proof
    Build, test and verify iOS app changes with the `proof` CLI. Use for any Xcode build or test, testing every branch of a stacked PR (gh stack), driving the iOS Simulator UI through the accessibility tree, taking screenshots to prove a UI change works, finding missing…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.