> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an iOS Simulator

> Create, inspect, install into, and release a remote iOS simulator session.

# Run an iOS Simulator

Create a remote iOS simulator session, open the signed stream URL in a browser,
install simulator-compatible app builds, and release the session when finished.

For CLI setup, see [CLI Quickstart](/cli/quickstart). For reusable app
artifacts, see [Assets](/cli/assets).

## Create a session

```bash theme={null}
run-cloud ios create
```

The response includes:

| Field                        | Use                                                                          |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `id`                         | run.cloud session id. Use it with `get`, `delete`, and `open-url`.           |
| `url`                        | Signed browser URL for the live simulator stream. Do not publish it in logs. |
| `status`                     | Session status: `active`, `released`, or `failed`.                           |
| `createdAt`                  | Session creation timestamp.                                                  |
| `releasedAt`                 | Release timestamp once the session is closed.                                |
| `expiresAt`                  | Session expiry timestamp when available.                                     |
| `inactivityTimeoutSeconds`   | Auto-close timeout in seconds, or `null` when disabled.                      |
| `inactivityCountdownSeconds` | Visible countdown duration before auto-close, or `null` when disabled.       |

For scripts, use JSON:

```bash theme={null}
run-cloud ios create --json
```

## Configure the session

```bash theme={null}
run-cloud ios create \
  --model iphone \
  --display-name "CI smoke" \
  --label env=ci \
  --inactivity-timeout 60s \
  --hard-timeout 10m \
  --json
```

Supported flags:

| Flag                            | Purpose                                                             |
| ------------------------------- | ------------------------------------------------------------------- |
| `--model MODEL`                 | Preferred simulator family: `iphone` or `ipad`.                     |
| `--region REGION`               | Preferred region when available.                                    |
| `--display-name NAME`           | Human-readable label.                                               |
| `--label KEY=VALUE`             | Repeatable metadata label.                                          |
| `--install FILE`                | Upload and install a local app artifact.                            |
| `--install-asset NAME_OR_ID`    | Install an already uploaded asset.                                  |
| `--inactivity-timeout DURATION` | Auto-close after user inactivity. Use `60s`, `3m`, `1h`, or `none`. |
| `--hard-timeout DURATION`       | Maximum requested session lifetime.                                 |
| `--rm`                          | Mark the session as auto-delete-on-exit intent.                     |
| `--json`                        | Machine-readable output.                                            |

If `--inactivity-timeout` is omitted or set to `none`, run.cloud creates a
metered session without inactivity auto-close. When a timeout is supplied, the
signed simulator URL carries that policy to the iOS simulator; the embedded iframe shows
the final 10-second countdown, ends the iOS simulator lease, and posts a session
ended message to its parent page.

Billing is account-level. Active sessions consume minute balance, and a depleted
balance closes the simulator session.

## Install an app

Install a local simulator build while creating the session:

```bash theme={null}
run-cloud ios create --install ./MyApp.tar.gz --json
```

Or upload once and reuse the artifact:

```bash theme={null}
run-cloud asset push ./MyApp.tar.gz -n my-app --json
run-cloud ios create --install-asset my-app --json
```

`--install` accepts `.tar.gz`, `.zip`, `.app` archives, and `.ipa` files. iOS
Simulator reliability still depends on the app being built for the simulator
runtime. Device-signed App Store IPAs are not a substitute for simulator builds.

## Open URLs and deep links

```bash theme={null}
run-cloud ios open-url https://example.com --id "$SESSION_ID"
run-cloud ios open-url myapp://settings --id "$SESSION_ID"
```

## Inspect sessions

```bash theme={null}
run-cloud ios list
run-cloud ios list --all
run-cloud ios get "$SESSION_ID" --json
```

`list` shows active sessions by default. Pass `--all` to include released
sessions.

## Release the session

```bash theme={null}
run-cloud ios delete "$SESSION_ID" --json
```

Explicit release charges the final started minute and closes the iOS simulator
session. If the account balance reaches zero, active sessions are closed
automatically.