> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/desktop-app/device-setup-wizard.md).

# Set up a device: Guided wizard

The guided wizard is the supported setup path. It installs the Android or Apple tooling, creates a device, and boots it.

{% hint style="info" %}
`Connect Device` → nothing connected → **Set up a device**
{% endhint %}

|                  |                                                                           |
| ---------------- | ------------------------------------------------------------------------- |
| **Platforms**    | Android · iOS                                                             |
| **What you get** | A booted Android emulator, or a booted iOS simulator                      |
| **First run**    | 5–10 minutes, most of it one download                                     |
| **Approval**     | Every shell command is shown to you and waits for Approve or Skip         |
| **Watch out**    | Safe to re-run any number of times — already-installed things are skipped |

## Prerequisites

* Drizz desktop app installed and signed in
* macOS 12 or later
* Homebrew installed
* Java from the Homebrew `openjdk@17` package (Android)
* Xcode installed from the Mac App Store and opened once (iOS)
* 20–30 GB free disk for Android · 40–50 GB free disk for iOS

## Start the wizard

1. Open the desktop app.
2. Go to **Connect Device**.
3. Select the platform — **Android** or **iOS**.
4. Click **Set up a device**. With no emulator or simulator present, Drizz offers the guided setup instead of an empty device list.
5. Approve or skip each command as it is presented.
6. Confirm the wizard finishes on a booted device listed in the device picker.

The manual guides — [Android setup](/desktop-app/android-setup.md) and [iOS simulator setup](/desktop-app/ios-simulator-setup.md) — cover the cases where the wizard fails, or where a configuration it doesn't create is required.

## Approval and risk badges

Each step displays the exact shell command it will run, with a risk badge, and waits for **Approve** or **Skip**. Nothing runs unapproved. Across a full run the wizard installs software, edits `~/.zshrc`, and downloads several gigabytes.

| Badge        | Means                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------ |
| **safe**     | Reads state, or installs into a Drizz-managed path. Nothing on your machine changes meaningfully |
| **moderate** | Installs software, or downloads several gigabytes                                                |
| **elevated** | Changes your shell environment — writing `ANDROID_HOME` and `PATH` into `~/.zshrc`               |

**Skip** passes over any step you would rather run yourself, or that is already set up in a non-standard location. The wizard continues from the next step.

## Re-running

Step 1 of every wizard is a diagnostic of what is already present. Anything already installed is skipped silently, and only missing items are presented for approval. Re-run the wizard after a failed step or an unwanted skip.

## Platform flows

{% tabs %}
{% tab title="Android" %}
Ten steps, ending with a booted emulator.

| #  | Step           | What it does                                                                               |
| -- | -------------- | ------------------------------------------------------------------------------------------ |
| 1  | Check          | Diagnoses what's already present — Android Studio, adb, the SDK, the system image          |
| 2  | Android Studio | Installs Android Studio with Homebrew                                                      |
| 3  | adb            | Installs the Android platform tools and links `adb` into the SDK path the emulator expects |
| 4  | SDK tools      | Downloads the command-line tools — `sdkmanager` and `avdmanager`                           |
| 5  | Env vars       | Writes `ANDROID_HOME` and `PATH` into `~/.zshrc`                                           |
| 6  | Licenses       | Accepts the Android SDK licenses                                                           |
| 7  | System image   | Downloads the Android 34 Google Play ARM64 image — about 1.8 GB, and the slow step         |
| 8  | Create AVD     | Creates an emulator called **DrizzPhone** on a Pixel 7 profile                             |
| 9  | Launch         | Starts the emulator in the background                                                      |
| 10 | Wait           | Waits for the emulator to finish booting                                                   |

A first run takes 15–30 minutes, almost all of it in step 7. Later runs take seconds, because steps 2 through 8 are skipped.

The emulator is named **DrizzPhone**, which identifies it in Android Studio's device list and in `adb devices` output.
{% endtab %}

{% tab title="iOS" %}
Two phases. Xcode cannot be downloaded programmatically — it ships through the Mac App Store or the Apple Developer Portal, and neither has a public download URL.

**Phase 1 — download gate.**

1. Click the wizard's link, which opens the App Store on the Xcode page.
2. Install Xcode.
3. Open Xcode once and dismiss the license screen.
4. Click **I've installed & opened Xcode** in the wizard.
5. Confirm the check passes. Drizz verifies that `/Applications/Xcode.app` exists. The command-line tools alone do not pass this check.

**Phase 2 — setup wizard.** Seven steps on the same approve/skip flow as Android, ending with a booted simulator.

Opening Xcode once is required because accepting the Xcode license from the command line only works after the first-launch license screen has been dismissed in Xcode's own window. Otherwise the license step waits for a click that cannot arrive in a background process. Creating a project is not required.

Simulator names come from Apple's tooling — iPhone 17, iPhone Air and so on. Drizz cannot rename them, so there is no iOS equivalent of DrizzPhone. The wizard boots the first available shut-down iPhone.
{% endtab %}
{% endtabs %}

## Known limitations

### Java must be in the Homebrew location

The SDK steps expect Java at the Homebrew `openjdk@17` path. Java installed elsewhere makes steps 4, 6, 7 and 8 fail. Install Java through Homebrew, or skip those steps and run them from a terminal that has your Java on its `PATH`.

### The license step can hang

Clicking "I've installed & opened Xcode" without opening Xcode starts a license step that never finishes. Quit the wizard, open Xcode, dismiss the license screen, and re-run.

### Android Studio may not land in `/Applications`

A known Homebrew cask behavior on first install. Reinstall the cask, then re-run the wizard:

```bash
brew reinstall --cask android-studio
```

### An emulator that crashes after launch fails quietly

Step 10 times out without reporting a cause. Read the emulator's own log:

```bash
cat /tmp/emulator.log
```

## Common mistakes

| What you do                                                    | What happens                                                                       |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Follow a manual Android Studio guide first                     | You'll do 20 minutes of work the wizard does for you, in paths it won't recognize  |
| Approve step 7                                                 | A 1.8 GB download over a bad connection. Start it somewhere with real bandwidth    |
| Skip step 5 because you don't want `~/.zshrc` edited           | Drizz still works, but `adb` and `emulator` won't be on your own terminal's `PATH` |
| Click "I've installed & opened Xcode" after only installing it | The license step hangs. Open Xcode once, then re-run                               |
| Re-run the wizard from scratch after one failed step           | Fine, and expected. It skips everything already done                               |
| Assume a timed-out step 10 means the wizard is broken          | The emulator crashed. Read `/tmp/emulator.log`                                     |

## Next

* [Android setup (manual)](/desktop-app/android-setup.md)
* [iOS simulator setup](/desktop-app/ios-simulator-setup.md)
* [Physical iOS device setup](/desktop-app/ios-physical-device.md)

***

*Last updated: 6 August 2026*