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

# App setup

> Build a testing-ready iOS app and package it for local or remote simulators.

Momentic supports iOS apps running on **local** and **remote simulators**. Real
devices are not supported.

## Prerequisites

For **local simulators** (macOS only):

* **Xcode** and **Xcode Command Line Tools**
* iOS simulator components for the target iOS version
* [**idb**](https://fbidb.io/docs/installation), Momentic uses idb to drive
  simulators

For **remote simulators**, no local Xcode is required once you have a build to
upload.

## Install Xcode

Download [Xcode](https://developer.apple.com/xcode/) from Apple's developer site
or the App Store. Open it once and accept the license agreement, then install
the command-line tools:

```bash theme={null}
xcode-select --install
```

After installing, verify that a Command Line Tools version is selected: open
**Xcode**, then **Settings**, then **Locations**, and confirm the **Command Line
Tools** dropdown has a version selected (e.g. `Xcode 26.2`). If the dropdown is
empty, select the latest version.

## Install simulator components

In Xcode, open **Xcode**, then **Settings**, then **Components**. If the
`iOS 26.2 + iOS 26.3.1 Simulator` component is not installed, click the download
icon.

## Install idb

Momentic uses idb to interact with local iOS simulators performantly. Follow
[idb's installation guide](https://fbidb.io/docs/installation).

## Build your app for testing

In Xcode, select **Product**, then **Build For**, then **Testing**. This
produces a `.app` bundle that Momentic can install on a simulator.

For a command-line build, use `xcodebuild`:

```bash theme={null}
xcodebuild \
  -workspace YourApp.xcworkspace \
  -scheme YourApp \
  -sdk iphonesimulator \
  -configuration Debug \
  -derivedDataPath build \
  build-for-testing
```

The `.app` bundle lands under `build/Build/Products/Debug-iphonesimulator/`.

## App requirements

* Builds must target **iOS simulator** (not a physical device).
* Debug builds work without extra configuration. Release builds may require
  additional code-signing configuration, simulator builds do not need a
  provisioning profile.

## Upload to a channel

Use [`momentic-mobile assets`](/cli-reference/momentic-mobile/commands/assets)
to upload the `.app` to a channel and tag:

```bash theme={null}
npx momentic-mobile assets upload ./build/Build/Products/Debug-iphonesimulator/YourApp.app \
  --channel dev \
  --tag 1.0.0
```

## Next steps

<CardGroup cols={2}>
  <Card title="Simulators" icon="tablet-screen-button" href="/platforms/ios/simulators">
    Local vs. remote simulators and device types
  </Card>

  <Card title="CI/CD" icon="play" href="/running-tests/ci/github-actions">
    Run iOS tests on every pull request
  </Card>
</CardGroup>