HeadSpin Documentation

Appium IDE

HeadSpin provides a desktop client for Appium development and debugging called Appium IDE. Download the latest version in your account settings.

HeadSpin Configuration

To connect Appium Desktop to a HeadSpin device, select New Session Window. In this new dialog window select the "HeadSpin" logo from the top navigation area.

headspin configuration

There are three values you will need to specify to connect to your HeadSpin account:

  • HeadSpin Host: The Android or iOS host you want to target.
  • HeadSpin Port: The port number of your host.
  • HeadSpin API Token: Your token can be retrieved from your account settings.

The HeadSpin Automation Configuration API endpoint provides the values for you to use.

HTTP Method Endpoint
GET https://{your-api-token}@api-dev.headspin.io/v0/devices/automation-config

Where you will replace the <code class="dcode">{your-api-token}</code> with the API token from your account settings. This endpoint will return a JSON object that has aforementioned values for the devices in your account. For example:

    "01a698280c34bee8@proxy-jp-tyo-1.headspin.io": {
        "device_location": {
            "city": "tyo",
            "carrier": "Sprint",
            "country_readable": "Japan",
            "city_readable": "Tokyo",
            "lat": 35.689487,
            "country": "jp",
            "lon": 139.691706
        "lock_url": "https://jp-tyo.headspin.io:7001/v0/<your_api_token>/lock",
        "working_dir": "/home/pbox/appium_tests/01a698280c34bee8",
        "capabilities": {
            "deviceName": "01a698280c34bee8",
            "autoAcceptsAlerts": "true",
            "udid": "01a698280c34bee8",
            "automationName": "UiAutomator2",
            "platformName": "Android",
            "noReset": "true"
        "host": "proxy-jp-tyo-1.headspin.io",
        "unlock_url": "https://jp-tyo.headspin.io:7001/v0/{api_token}/unlock",
        "driver_url": "https://jp-tyo.headspin.io:7001/v0/{api_token}/wd/hub",
        "device_carrier": {
            "network_subtype": "",
            "network_connected": true,
            "network_type": "WIFI",
            "phone_network": "UNKNOWN",
            "carrier": "Sprint"
        "os": "android",
        "control_url": "https://jp-tyo.headspin.io:7100"

The value of the <code class="dcode">"host"</code> key is the HeadSpin Host and the port shown in the <code class="dcode">"driver_url"</code> is the HeadSpin Port.

HeadSpin Host HeadSpin Port
proxy-jp-tyo-1.headspin.io 7001

Additionally the optimal minimum desired capabilities will be returned for every device for you to include. For Android, include your <code class="dcode">appPackage</code> and <code class="dcode">appActivity</code>. For iOS include your app's <code class="dcode">bundleId</code>. If you would like to use the Appium <code class="dcode">app</code> capability to install an app and launch, simply provide an <code class="dcode">https</code> link to your app.

For convenience, HeadSpin has created convenience capabilities you can use to initiate a Performance Session and specify a particular Appium Server version for your test.

Capability Notes
headspin.capture You can set this to true or false
headspin.appiumVersion A given Appium Server version, e.g. 1.20.2