---
title: "Local device setup"
section: "Agent Pool & Device Farm"
description: "Set up an Android emulator and Appium, Appium with the Windows driver and WinAppDriver on a Windows PC, or Appium with the Mac2 driver on a Mac, on the computer that runs your SmartestQA agent, then check the device in Connected Devices."
url: https://docs.smartestqa.ai/en/agent-pool-local-setup.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "local emulator setup local desktop setup android studio avd emulator adb devices appium 4723 uiautomator2 node.js winappdriver windows driver developer mode macos mac desktop mac2 driver xcode accessibility screen recording input monitoring automationmodetool connected devices appium running real devices"
---
# Agent Pool & Device Farm: Local device setup

Mobile and desktop tests on your own computer need three things next to the agent: the device or app, Appium on port 4723 and the right driver. These guides walk you through them.

## In short

**On this page you can**

- Install Android Studio, the SDK parts and an emulator for local mobile tests.
- Install and start Appium with one command and keep it running.
- Prepare a Windows PC (Windows driver, WinAppDriver) or a Mac (Mac2 driver, Xcode) for desktop tests.
- Check that SmartestQA sees your phone or emulator and that Appium runs.

**How to use it**

1. Open Device Farm › Test Agents and select your Localhost agent.
2. Open Local Emulator Setup (MOBILE) or Local Desktop Setup (DESKTOP on Windows); on a Mac follow the macOS steps on this page.
3. Work through the steps with Next ; copy each command with its copy icon.
4. Start the agent with the API key shown in the last step.
5. In MOBILE projects, check Connected Devices for the device and the green Appium chip.

> **Note: You need**
>
> A MOBILE or DESKTOP project, and the SmartestQA agent on the same computer as the device or app ([Install an agent](https://docs.smartestqa.ai/en/quick-start-connect.html#install-agent)). The guides are in **Device Farm** › [**Test Agents**](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-list), right panel, second tab. In WEB projects the tab is not shown.

Each guide is a list of steps. Click a step title to jump to it, or use **Back** and **Next**. After the last step, **Finish** shows “You're all set!”; **Restart** takes you back to step 1. The guide does not check your machine: it tells you what to run and what you should see.

## Android emulator on your computer

Tab **Local Emulator Setup**, titled **Local Android Emulator Setup**. Works on Windows, macOS and Linux.

1. **Install Android Studio**

   The Windows, Mac and Linux buttons open Google’s Android Studio download page. The installer includes the SDK, the emulator and the tools.
2. **Install Required SDK Components**

   In Android Studio go to **More Actions › SDK Manager** and make sure these are installed: Android SDK Platform (API 34 or newer), Android SDK Build-Tools, Android Emulator, Android SDK Platform-Tools (adb).
3. **Create a Virtual Device (AVD)**

   **Tools › Device Manager › Create Device**. Pick a phone such as Pixel 7, a system image such as API 34 with Google APIs, then Finish.
4. **Start the Emulator**

   In Device Manager click ▶ next to the virtual device. The emulator window opens within seconds.
5. **Verify the Device with adb**

   In a terminal run the command below.

   Terminal

   ```text
   adb devices
   ```

   The emulator is listed as `device`, not `offline`.
6. **Install Appium Server**

   Appium is the bridge between SmartestQA and the device. It needs Node.js; use a current LTS version, because older Node.js versions make the Appium install fail with `ERR_REQUIRE_ESM`. Paste this single line: it installs Appium and the Android driver, then starts the server.

   Terminal

   ```text
   npm install -g appium && appium driver install uiautomator2 && appium
   ```

   You see “Appium REST http interface listener started on http://0.0.0.0:4723”. The terminal stays busy; that is the server running.
7. **Connect the Smartest Agent**

   Start the agent from the [**Download Client**](https://docs.smartestqa.ai/en/agent-pool-agents.html#download-client) tab with the API key shown in this step (it has a copy icon). When the dot turns green, the emulator is ready.

> **Warning: Do not close the Appium terminal**
>
> Appium runs in the foreground of that terminal. Closing it makes the next test fail with “Server Unreachable / ECONNREFUSED 127.0.0.1:4723”. To start it again later, run `appium` in a new terminal.

A real Android phone works the same way: connect it by USB with USB debugging on, and once `adb devices` lists it as `device`, SmartestQA sees it under **Real Devices**. iOS devices and simulators need the agent on a Mac.

When the device is ready, pick it as the device of your run: in **Configuration** › **Project Panel** › [**Mobile Config**](https://docs.smartestqa.ai/en/project-settings-mobile.html) choose the local device (see [Mobile and desktop apps](https://docs.smartestqa.ai/en/quick-start-connect.html#connect-mobile-desktop)), or select it when you set up a [pipeline](https://docs.smartestqa.ai/en/schedule-create.html) in **Schedule**. For recording, see [Discover › Mobile](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#mobile).

## Windows machine for desktop tests

Tab **Local Desktop Setup**, titled **Local Desktop (Windows) Setup**. The tab covers Windows; for a Mac, see [Mac for desktop tests](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#macos-desktop).

1. **Install Node.js**

   Appium is a Node.js application. Check your version with the command below; **Download Node.js (Windows)** opens the Node.js download page. Use a current LTS version.

   PowerShell

   ```text
   node -v
   ```
2. **Install Appium & Windows Driver**

   Copy the single PowerShell line shown in this step and run it. It downloads and runs the SmartestQA setup script, which installs Appium and the Windows driver, downloads and installs the latest WinAppDriver (Windows asks for administrator approval once), turns on Developer Mode, frees port 4723 and starts Appium.

   You see “Appium REST http interface listener started on http://0.0.0.0:4723”. Leave this terminal open.
3. **Enable Developer Mode**

   If it is still off: **Settings › Privacy & Security › For developers**, turn **Developer Mode** on, confirm, and restart if Windows asks. Without it, WinAppDriver crashes mid-session and the test stops with “session terminated / driver unreachable”.
4. **Verify the Windows Driver**

   Open a second terminal, leaving the Appium one running, and run the command below.

   PowerShell

   ```text
   appium driver list --installed
   ```

   `windows` is in the list of installed drivers.
5. **Connect the Smartest Agent**

   Start the agent with the API key shown in this step. When the dot turns green, the machine is ready for desktop runs and the [**Desktop Recorder**](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop).

Next: configure the application in [**Desktop Configuration**](https://docs.smartestqa.ai/en/project-settings-desktop.html) (see [Mobile and desktop apps](https://docs.smartestqa.ai/en/quick-start-connect.html#connect-mobile-desktop)) and record it with the [Desktop Recorder](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop).

## Mac for desktop tests

DESKTOP projects can test macOS apps as well as Windows apps. On a Mac the runner drives the app with Appium’s Mac2 driver, which works through Apple’s XCTest. The **Local Desktop Setup** tab shows the Windows steps, so prepare a Mac with the steps below. You need an administrator account on the Mac for the setup.

1. **Install Xcode**

   Install Xcode 13 or newer from the App Store and open it once, so it finishes installing its components. The Command Line Tools alone are not enough. Then make the full Xcode the active one.

   Terminal

   ```text
   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
   ```
2. **Install Appium and the Mac2 driver**

   Appium needs Node.js; use a current LTS version (check with `node -v`). Then install Appium and the Mac2 driver.

   Terminal

   ```text
   npm install -g appium
   appium driver install --source=npm appium-mac2-driver
   ```
3. **Verify the Mac2 driver**

   Run the commands below. The second one checks the driver’s requirements, such as Xcode, and says what is missing.

   Terminal

   ```text
   appium driver list --installed
   appium driver doctor mac2
   ```

   `mac2` is in the list of installed drivers.
4. **Allow the macOS permissions**

   Open **System Settings › Privacy & Security** and allow the items in the table below. “The app that runs the agent” is SmartTest-Desktop, or Terminal if you start the agent from a Terminal window. Xcode Helper is in the folder this command opens; drag it into the Accessibility list.

   Terminal

   ```text
   open /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Agents/
   ```

   | Permission | Allow for | Needed for |
   | --- | --- | --- |
   | Accessibility | Xcode Helper and the app that runs the agent | Test runs and the [**Desktop Recorder**](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop): clicks, keys and reading the app’s elements. |
   | Screen Recording | The app that runs the agent | Screenshots of recorded steps. Without it, the Desktop Recorder records the steps without screenshots. |
   | Input Monitoring | The app that runs the agent | The Desktop Recorder: capturing your clicks and key presses. |

   Then run this command once, so macOS does not ask for authentication each time a test session starts.

   Terminal

   ```text
   automationmodetool enable-automationmode-without-authentication
   ```
5. **Install and connect the macOS agent**

   In [**Download Client**](https://docs.smartestqa.ai/en/agent-pool-agents.html#download-client) click **Mac** (`SmartTest-Desktop-macOS-latest.zip`), or copy the macOS command from [**Install Via CLI**](https://docs.smartestqa.ai/en/agent-pool-agents.html#install-cli) ([Download Client](https://docs.smartestqa.ai/en/agent-pool-agents.html#download-client)). Start the agent with your agent’s API key ([The API key](https://docs.smartestqa.ai/en/agent-pool-agents.html#api-key)).

   The agent’s dot turns green. The Mac is ready for desktop runs and the [**Desktop Recorder**](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop).

Appium must be running when a desktop test starts, at the **Appium Server URL** of Desktop Configuration (default `http://localhost:4723`). If Appium is installed but not running, the agent tries to start it; you can also start it yourself with `appium` in a terminal and leave that terminal open. The first time you open the Desktop Recorder on a Mac, the agent builds its macOS recorder with Xcode, so that first start takes longer.

Next: in [**Desktop Configuration**](https://docs.smartestqa.ai/en/project-settings-desktop.html) choose the platform **macOS (Mac2Driver)** and add the app with its **Bundle ID** (for example `com.example.MyApp`) or its **App Path** (for example `/Applications/MyApp.app`); see [Desktop Configuration](https://docs.smartestqa.ai/en/project-settings-desktop.html). Then record it with the [Desktop Recorder](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop).

## Check the device: Connected Devices

In MOBILE projects the agent list has a **Connected Devices** group under your online Localhost agent. It lists what that agent can reach right now.

- **Appium chip**: green **Appium** when the server answers (hover for version and address), red [**Appium off**](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-appium-not-running) when it does not, with “Appium server not found” and the hint to run `appium` in a new terminal.
- **Groups**: **Real Devices** and **Emulators / Simulators**. An Android project shows only Android devices, an iOS project only iOS devices, a MOBILE project both.
- **Empty**: “No Android devices found” or “No iOS devices found (macOS agent required)”.
- **Refresh** asks the agent again. Nothing is shown while the agent is Offline.
- **[**Use Device Live**](https://docs.smartestqa.ai/en/agent-pool-live-device.html#local-device)** on a device row opens its screen in the browser. See [Live device sessions](https://docs.smartestqa.ai/en/agent-pool-live-device.html#local-device).

## If something goes wrong

- [“Appium server not found” / “Appium off”](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-appium-not-running)
- [“Server Unreachable / ECONNREFUSED 127.0.0.1:4723”](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-econnrefused)
- [Appium install fails with ERR_REQUIRE_ESM](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-require-esm)
- [adb lists the emulator as offline](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-adb-offline)
- [“No Android devices found” / “No iOS devices found”](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-no-local-devices)
- [Desktop test stops with “session terminated / driver unreachable”](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-session-terminated)
- [“Xcode is missing or not selected (macOS)”](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-mac-xcode)
- [“A macOS permission is missing”](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-mac-permission)
