🚀 See how 20+ AI Agents can make your QA faster and smarter. Join 10k+ QAs at global leadership summit! Register Now
No Result Found
Connect & Get help from fellow developers on our Discord community. Ask the CommunityAsk the Community

Get started with device tunneling

This guide walks you through the installation, configuration, and initial use of device tunneling.

Device tunneling establishes a secure connection between your local machine and a BrowserStack Private Device, enabling you to use native debugging tools as if the device were physically plugged in. This guide walks you through the setup process to get your first tunnel running.

Prerequisites

Before you begin, ensure you have the following:

  • A BrowserStack Username and Access Key. You can obtain your userName and accessKey from the Account & Profile section on the dashboard.
    If you have not yet created an account, sign up for a free trial.

  • A BrowserStack Enterprise plan with access to Private Devices. This feature is exclusively available for Private Devices to ensure stability and security.

  • Administrator rights on your local machine to install and run the required software.

  • The device tunneling binary (browserstack-sdk) downloaded for your operating system.

Execute the binary

After downloading the binary, make it executable. On macOS and Linux, run:

bash
Copy icon Copy

Configuration

You can provide your BrowserStack credentials using CLI flag or a configuration file.

Set your credentials as environment variables for secure, temporary access.

bash
Copy icon Copy

For a more permanent setup, create a device-tunnel.yml file in the same directory as the binary.

device-tunnel.yml
Copy icon Copy

Running your first tunnel

You can establish a tunnel using two modes: Interactive Mode for a guided experience or CI/CD Mode for automated command-line workflows.

Follow these steps for scripted or automated environments:

Start an Appium session

The device tunnel is anchored to a BrowserStack App Automate session.

  • Start a standard Appium test session on your desired private device.

Important: You must include the deviceTunnel: "true" capability in your Appium configuration.

  • Once the session begins, copy the session_id from the App Automate dashboard.

Start the orchestrator

  • In a terminal, run the start command to launch the orchestrator, which manages tunnel connections. Keep this process running. You can run it in the foreground to view console logs or in the background.
bash
Copy icon Copy

Expected Output:

# Starting Device Tunnel Orchestrator...
# WebSocket server listening on port 8080
# Orchestrator ready for tunnel requests
  • Use device-tunnel sessions to list all the running sessions where you can start a tunnel.

Establish the tunnel

Open a new terminal and use the connect command with the session_id you copied.

bash
Copy icon Copy

Expected Output:

# Creating tunnel for session: YOUR_SESSION_ID
# TCP Server: localhost:7005
# Tunnel connected successfully
# ADB commands will be forwarded to device

For a list of CLI options, refer to the CLI reference & management documentation.

Verify the connection

Once the tunnel is established, your native tools can see the remote device.

adb devices

idevice_id -l

Expected Output:

# List of devices attached
# localhost:7005    device

# <device-uuid>

Start testing

The remote device is now connected to your local machine as if it were plugged in via USB.

You can now:

  • Run test scripts from any custom framework.
  • Use adb logcat or idevicesyslog to view device logs in real-time.
  • Manage port forwarding with adb forward for android, and iproxy for iOS devices.

Interactive mode provides a simple, menu-driven interface to manage your sessions and tunnels.

  • Launch the interactive mode by running the following command:
bash
Copy icon Copy
  • Follow the on-screen menu to list your active sessions and connect to a device.

Start a new session: Interactive Mode - Start a new session

Select a device to connect: Interactive Mode - Select a device

Tunnel established successfully: Interactive Mode - Tunnel established

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked





Thank you for your valuable feedback

  • ON THIS PAGE

    Is this page helping you?

    Yes
    No

    We're sorry to hear that. Please share your feedback so we can do better

    Contact our Support team for immediate help while we work on improving our docs.

    We're continuously improving our docs. We'd love to know what you liked





    Thank you for your valuable feedback!

    Talk to an Expert
    Download Copy Check Circle