Device Node CLI Reference

See More

Complete command-line reference for Device Node. The Device Node connects your physical devices, emulators, and simulators to DeviceLab, making them accessible for remote testing.

Synopsis

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- [OPTIONS]

Replace YOUR_ORG_KEY with your organization ID from the DeviceLab dashboard.

Options

--name <string>

Set a custom name for this device node. Default: system hostname.

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --name "NYC-Office-MacMini-2"

Naming tips: Use location + machine type for easy identification:

  • NYC-Office-MacMini-2
  • SF-QA-Lab-Linux-3
  • Berlin-Remote-MacPro
  • Home-Sarah-MacBook

The name appears in:

  • DeviceLab dashboard
  • Log files
  • Device allocation

--enable-turn

Enable TURN relay for networks that require it.

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --enable-turn

When to use:

  • Behind symmetric NAT
  • Strict corporate firewalls
  • When direct WebRTC connection fails

Privacy Note: TURN relay routes traffic through third-party servers.

--apple-team-id <string>

Apple Team ID for iOS physical device testing with Maestro.

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --apple-team-id "ABCD1234EF"

Required for: Running Maestro tests on physical iOS devices (not simulators).

Find your Team ID:

bash 
# Method 1: Xcode
# Xcode → Preferences → Accounts → View Details

# Method 2: Command line
security find-identity -v -p codesigning | grep "Apple Development"

--simulators <string>

Comma-separated list of iOS simulators to add.

bash 
# Basic usage
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --simulators "iPhone 16,iPad Pro"

# With specific iOS versions
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --simulators "iPhone 16:18.0,iPad Pro:17.0"

Format: "DeviceName" or "DeviceName:iOSVersion"

Available simulators: Run xcrun simctl list devices to see installed simulators.

--emulators <string>

Comma-separated list of Android emulators (AVD names) to add.

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --emulators "Pixel_8,Pixel_Tablet"

Available emulators: Run emulator -list-avds to see installed AVDs.

--upgrade-maestro

Patch your Maestro installation with DeviceLab’s modified JARs to enable additional features.

bash 
deviceNode --upgrade-maestro

What it does:

  1. Backs up existing JARs to ~/.maestro/lib/maestro_backup_<timestamp>/
  2. Downloads and installs patched JARs
  3. On macOS: Downloads iOS runner to ~/.maestro/maestro-ios-xctest-runner/

Features enabled by patch:

Feature Without Patch With Patch
Run tests on single device ✅ ✅
Run tests on multiple devices in parallel ❌ ✅
Run tests on iOS Simulators ✅ ✅
Run tests on physical iPhones (macOS) ❌ ✅

Note: If you start Device Node without the patch, a warning is displayed but operation continues with limited functionality.

Exit Codes

Code Description
0 Normal exit
1 General error (registration failed, TLS error)
2 Singleton lock failed (another instance running)
3 TURN required but not enabled

Log Files

Log Location
Main log ./log/devicenode.log
Device logs ./log/device/
Appium logs ./log/appium/

Examples

Basic Usage

bash 
# Connect physical devices only
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh

QA Lab Setup

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --name "Austin-QA-Lab-MacMini-1"

With iOS Simulators

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --name "SF-Office-MacPro" \
  --simulators "iPhone 16,iPhone 15 Pro,iPad Air"

With Android Emulators

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --name "Seattle-Dev-Linux-1" \
  --emulators "Pixel_8,Pixel_7_Pro,Pixel_Tablet"

Full Production Setup

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --name "London-Office-MacMini-2" \
  --simulators "iPhone 16:18.0,iPad Pro:17.0" \
  --emulators "Pixel_8,Pixel_Tablet" \
  --apple-team-id "ABCD1234EF"

Corporate Network (TURN Required)

bash 
curl -fsSL https://app.devicelab.dev/device-node/YOUR_ORG_KEY | sh -s -- \
  --name "Tokyo-Office-Mac" \
  --enable-turn

Network Detection

Device Node automatically detects network type using STUN servers:

NAT Type TURN Required
full_cone No
restricted No
port_restricted No
symmetric Yes

If symmetric NAT detected and --enable-turn not set, exits with code 3.

Retry Behavior

  • Connection retries: 3 attempts
  • Retry delay: 5 seconds
  • Retried errors: Health check failures
  • Non-retried errors: Authentication, configuration errors

Graceful Shutdown

Handles SIGINT (Ctrl+C) and SIGTERM:

  1. Stops device monitors
  2. Cleans up resources
  3. Disconnects from server
  4. Closes gRPC connection

See Also