1. Docs
  2. Resources
  3. Agent Pool & Device Farm
  4. Local device setup

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.

7 min read Updated CustomersAdmins

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.

You need

A MOBILE or DESKTOP project, and the SmartestQA agent on the same computer as the device or app (Install an agent). The guides are in Device FarmTest Agents, 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
    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
    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 tab with the API key shown in this step (it has a copy icon). When the dot turns green, the emulator is ready.

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 ConfigurationProject PanelMobile Config choose the local device (see Mobile and desktop apps), or select it when you set up a pipeline in Schedule. For recording, see Discover › 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.

  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
    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
    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.

Next: configure the application in Desktop Configuration (see Mobile and desktop apps) and record it with the Desktop Recorder.

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
    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
    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
    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
    open /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Agents/
    PermissionAllow forNeeded for
    AccessibilityXcode Helper and the app that runs the agentTest runs and the Desktop Recorder: clicks, keys and reading the app’s elements.
    Screen RecordingThe app that runs the agentScreenshots of recorded steps. Without it, the Desktop Recorder records the steps without screenshots.
    Input MonitoringThe app that runs the agentThe 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
    automationmodetool enable-automationmode-without-authentication
  5. Install and connect the macOS agent

    In Download Client click Mac (SmartTest-Desktop-macOS-latest.zip), or copy the macOS command from Install Via CLI (Download Client). Start the agent with your agent’s API key (The API key).

    The agent’s dot turns green. The Mac is ready for desktop runs and the Desktop Recorder.

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 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. Then record it with the Desktop Recorder.

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 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 on a device row opens its screen in the browser. See Live device sessions.

If something goes wrong#

Didn’t find your answer?Write to support with your project name and what you see on screen.

info@smartestqa.ai
© 2026 Selenity Technology · SmartestQAsmartestqa.aiThis page as MarkdownChecked against smarttest-fe predev 2a8c79cc (OnPremiseEmulatorSetup, OnPremiseDesktopSetup, HostDevicesInline, desktopErrors, DesktopErrorPanel, downloadAssets), smarttest-testsuite (run_desktop_agent.py, helpers/desktop_helper.py, helpers/desktop_errors.py, apps/desktop/live_recorder_mac.py, smarttest-setup.sh)