Set up virtualUSB Learn how to set up virtualUSB on your personal computer so you can debug local and private devices. Before you start You’ll need a personal computer with the following system specifications: macOS Windows Linux macOS Monterey 12 or later. Xcode 13 or later. Use a version that supports the iOS versions you test. Devices running iOS 17.4 or later also require Xcode for automatic pairing. For supported iOS versions, see Considerations in Start debugging. Windows 10 or later. A 64-bit x86 (x86_64) computer running one of the following: Ubuntu 22.04 or later (Debian-based). Red Hat Enterprise Linux (RHEL) 9 or later (Red Hat-based). For iOS devices: usbmuxd from libimobiledevice. The supported distributions include usbmuxd by default. virtualUSB for Linux is a command-line tool only. There is no desktop app. For supported iOS versions, see Considerations in Start debugging. Administrative privilege is required to set up and use virtualUSB. For your organization’s private or local devices, an organization admin must also enable virtualUSB on the devices' host machines. Android requirements To connect to Android devices via virtualUSB, you must install Android Debug Bridge (adb) from the Android SDK Platform-Tools package. If you don’t already have adb on your workstation, download it from Android or install an IDE like Android Studio. Follow the official Android developer guide to set up the required environment variables for adb. You can also run the below example commands to set the environment variables. macOS with Zsh shell Windows Linux with Bash shell export ANDROID_HOME=path/to/Android/sdk export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools Replace path/to/Android/sdk with the actual location of SDK installation directory (the folder containing platform-tools). set ANDROID_HOME=C:\path\to\Android\Sdk set PATH=%PATH%;%ANDROID_HOME%\tools;%ANDROID_HOME%\platform-tools Replace C:\path\to\Android\Sdk with the actual location of SDK installation directory (the folder containing platform-tools). export ANDROID_HOME=path/to/Android/sdk export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools Replace path/to/Android/sdk with the path to the Android SDK folder that contains platform-tools. To keep these variables across sessions, add both lines to ~/.bashrc. For macOS only: Prepare debug symbols for iOS devices If your network has a low bandwidth, fetching debug symbol files for Xcode via virtualUSB can be slow and unreliable. In such cases, you’ll need to manually prepare the debug symbols, which are specific to the device’s iOS version. If needed, contact our Support team and request the debug symbols for your devices. Then, copy the debug symbols to your local Mac folder: /Users/<your username>/Library/Developer/Xcode/iOS DeviceSupport/ Clean up previous virtualUSB version before installing new version If you have installed virtualUSB previously, we recommend uninstalling the old version before installing a new one. See Uninstall virtualUSB for guidance. Download virtualUSB For Cloud and Hybrid customers, select the Download button on the navigation bar of the Kobiton Portal, then select the virtualUSB installer for your operating system: virtualUSB for Mac virtualUSB for Windows virtualUSB for Linux (Debian-based) virtualUSB for Linux (Red Hat-based) Each entry downloads the latest virtualUSB 2 installer from Kobiton’s public download site. No additional sign-in is required. For Standalone/On-Prem customers, Standalone installations include the virtualUSB installers for macOS, Windows, Debian-based Linux, and Red Hat-based Linux. Contact Kobiton Support for the latest download links if you have trouble finding them. Install virtualUSB macOS Windows Linux Do not install virtualUSB on a Mac that has an existing deviceConnect installation. Open the downloaded .pkg file to begin the installation. Select Continue and follow the on-screen guide to install. After the installation completes, go to the Applications folder in Finder, and open virtualUSB: If this is the first time launching the app, provide the administrator password to install the required daemon: The daemon needs to be installed for virtualUSB to work. If you dismiss the above pop-up by mistake, quit and re-open virtualUSB to view and accept the prompt. Agree to the License terms and select Continue: Open the downloaded .msi file. When the virtualUSB Setup Wizard starts, select Next, then follow the on-screen guide to install. During installation, select Yes in the User Account Control pop-up to give the installer administrative permission: When your installation is complete, launch virtualUSB from the Windows Start menu: Upon the first time launching the app, you must agree to the License terms and select Continue: Open a terminal in the folder that contains the downloaded installer, then install the package for your distribution: Debian-based (Ubuntu): sudo apt-get install ./<virtualusb-deb-file> Red Hat-based (RHEL): sudo dnf install ./<virtualusb-rpm-file> Replace <virtualusb-deb-file> or <virtualusb-rpm-file> with the file name of the installer you downloaded. The installer adds vusb to the system PATH, so vusb runs from any directory. To confirm the installation, run: vusb --version Launch virtualUSB and log in On Linux, sign in with the vusb login command instead of the desktop app. Use the values in the following tabs for the --apibaseurl and --grpcbaseurl flags if your organization uses a custom domain or Standalone/On-Prem. Cloud/Hybrid Cloud/Hybrid with custom domain Standalone/On-Prem Launch virtualUSB and sign in using your email address and password or Kobiton API key. Select the Login to your custom domain portal checkbox in the login screen. Input the values for the two additional fields as below, replacing <custom-domain> with the customer’s domain name: API Base Url: https://api.<custom-domain>.com API GRPC Base Url: https://proxy-api-public-grpc-server.<custom-domain>.com Input the Username/Email and Password/API Key to log in. The values for API Base Url and API GRPC Base Url are remembered and prefilled the next time you open the app. Configure your computer for Standalone Portal with a self-signed SSL certificate before signing in. Select the Login to your custom domain portal checkbox on the login screen Input the values for two the additional fields as <http/https>://<Portal private domain or IP>:<REST API port>, where: <http/https>: if the Portal server uses HTTPS, then use https. Otherwise, use http. <Portal private domain or IP>: if the Portal server has a private domain, use its private domain. Otherwise, use the Portal server’s IP address. <REST API port>: For API Base Url, use 3000. For API GRPC Base Url, use 3001. Example: API Base Url: http://129.168.36.24:3000 or https://www.acme.local:3000 API GRPC Base Url: http://129.168.36.24:3001 or https://www.acme.local:3001 Then input the Username/Email and Password/API Key to log in.