> For the complete documentation index, see [llms.txt](https://docs.qapilot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qapilot.io/getting-started/set-up-qapilot/private-device-farm.md).

# Private Device Farm

The **Private Cloud Listener** is an npm package installed on your Mac Mini/Windows machine. It authenticates with QApilot, receives test jobs, and controls the attached devices. Currently this is support for android devices only.

<figure><img src="https://1727045651-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff7DuCvkprTM62hS3tKQF%2Fuploads%2F8avcjcZPjbclhdhFXwgh%2Fimage.png?alt=media&amp;token=8fbcae4d-154c-44c5-a3bd-73dc3ea78417" alt=""><figcaption></figcaption></figure>

***

### Prerequisites

Before starting setup, confirm the following are in place.

**Hardware & OS**

* [ ] Mac Mini or Windows device
* [ ] Android device(s) connected via USB, or emulator(s) configured
* [ ] Stable network connection between Mac Mini and QApilot servers

**Software**

* [ ] Node.js 18 or later installed
* [ ] npm 9 or later installed
* [ ] Appium 2.x installed globally (`npm i -g appium`)
* [ ] Android SDK installed and `adb` available in PATH
* [ ] ChromeDriver downloaded (or auto-download enabled)
* [ ] Java JDK 11 or later installed
* [ ] `ANDROID_HOME` environment variable set correctly

**QApilot Access**

* [ ] QApilot account (with Tenant Admin role for configuration)
* [ ] Access to the QApilot Settings panel
* [ ] Private Device Farm feature enabled on your tenant (contact support if not visible)
* [ ] Test app uploaded to QApilot and a Test Plan ready to run

**Devices**

* [ ] USB debugging enabled on each Android device
* [ ] Each device trusted on the Mac Mini (`adb devices` shows them as `authorized`)
* [ ] Device screen remains on during testing (disable auto-lock)
* [ ] No other ADB sessions active on target devices

***

### Setup

#### Step 1 - Generate credentials in QApilot (Tenent Admin)

1. Sign in to QApilot and navigate to **Settings → Private Device Farm**.
2. Click **Add New Listener**.
3. Enter a name for this listener (e.g. `mac-mini-lab-01`).
4. Copy the **Listener Token** shown - this is only displayed once.
5. Note your **Username**, **Password**, and the **Server URL** for your tenant.

{% hint style="danger" %}
Store the Listener Token securely. It cannot be retrieved after this step. If lost, generate a new one from the same Settings page.
{% endhint %}

**Credential reference**

| Field        | Description                                          |
| ------------ | ---------------------------------------------------- |
| `--username` | Your QApilot account email                           |
| `--password` | Your QApilot account password                        |
| `--token`    | Listener token generated in this step                |
| `--server`   | Your tenant API URL (e.g. `https://api.qapilot.io/`) |

***

#### Step 2 - Start the Appium server

Run the following command on the same Mac Mini where the listener is installed:

```bash
appium \
  --port 4723 \
  --allow-insecure chromedriver_autodownload,adb_shell \
  --base-path=/wd/hub \
  --allow-cors
```

**Configuration reference**

| Flag               | Value                       | Purpose                                      |
| ------------------ | --------------------------- | -------------------------------------------- |
| `--port`           | `4723`                      | Port Appium listens on                       |
| `--allow-insecure` | `chromedriver_autodownload` | Auto-downloads matching ChromeDriver         |
| `--allow-insecure` | `adb_shell`                 | Allows ADB shell commands for device control |
| `--base-path`      | `/wd/hub`                   | Standard WebDriver base path                 |
| `--allow-cors`     | —                           | Allows cross-origin requests from QApilot    |

***

#### Step 3 - Install the Private Cloud Listener

**Install** (on Mac Mini)

```bash
npm i -g qapilot-privatecloud-listener-1.2.0.tgz
```

**Upgrade (existing installations)**

```bash
npm uninstall -g qapilot-listener
npm i -g qapilot-privatecloud-listener-1.2.0.tgz
```

**Start the listener**

```bash
qapilot-listener \
  --username <your-email> \
  --password <your-password> \
  --token <your-listener-token> \
  --server https://api.qapilot.io/
```

When the listener starts successfully, it will appear as **Online** in **Settings → Private Device Farm** in QApilot.

***

#### Step 4 - Assign devices in QApilot

1. Go to **Settings → Private Device Farm** in QApilot.
2. Confirm your listener shows as **Online**.
3. Devices detected by the listener will appear in the device list.
4. Assign each device a display name and set its state to **Active**.

***

#### Step 5 - Configure app and test management

1. Upload your `.apk` file via **App Management** in QApilot.
2. Open your test plan and assign it to one or more private devices.
3. Set the execution environment to **Private Device Farm**.
4. Save and run a test to verify the end-to-end connection.

***

### Validation Checklist

Run through these checks after completing setup to confirm everything is working correctly.

* [ ] Listener appears as **Online** in QApilot Settings
* [ ] All target devices show in the device list with correct names
* [ ] `adb devices` shows all physical devices as `authorized`
* [ ] Emulators are visible and in a running state
* [ ] Appium server responds at `http://localhost:4723/wd/hub/status`
* [ ] Test app is uploaded and visible in App Management
* [ ] Test suite is assigned to at least one private device
* [ ] A manual test run completes without connection errors
* [ ] Test results appear in the QApilot results dashboard
* [ ] Pass / fail status is captured correctly
* [ ] Device state updates to **Busy** during a test run
* [ ] Device state returns to **Online** after a test completes
* [ ] CI/CD pipeline trigger reaches private devices (if applicable)
* [ ] No ADB conflicts observed during parallel test runs
* [ ] ChromeDriver auto-download succeeds on first WebView test
* [ ] Listener reconnects automatically after a network interruption

***

### Security Considerations

* The Listener Token grants access to your QApilot tenant. Treat it like a password and store it in a secrets manager, not in plain text or source control.
* Devices on the private farm are isolated to your tenant and are not shared with other QApilot users.
* Rotate listener tokens periodically via **Settings → Private Device Farm**.
* Restrict Mac Mini access to authorised personnel only. Anyone with machine access can view running Appium sessions.
* Use a dedicated QApilot service account for the listener rather than a personal account.

***

### Troubleshooting

**Listener shows as Offline**\
Check that the listener process is running on the Mac Mini. Verify the `--server` URL and credentials are correct. Confirm outbound HTTPS access to `api.qapilot.io` is not blocked by a firewall.

**Devices not appearing in QApilot**\
Run `adb devices` on the Mac Mini and confirm devices show as `authorized`. Restart the ADB server with `adb kill-server && adb start-server`, then restart the listener.

**Appium fails to start**\
Verify `ANDROID_HOME` is set and that `adb` is available in your PATH. Ensure no other process is using the specific port 4723.

**Tests fail immediately with a connection error**\
Confirm Appium is running and the base path is set to `/wd/hub`. Check that the correct device UDID is being passed to the test configuration.