Join our Discord
Workflows and limitations
Common Device Tunnel workflows and known limitations of Device Tunnel CLI
Review the common workflows below to structure your automation around Device Tunnel, and review the limitations before you implement it. Understanding these constraints helps you plan workarounds and avoid common issues.
Common workflows
Single-device workflow
Multi-device parallel workflow
For partial failures, where some devices succeed and some fail, the CLI reports each failure individually and returns a non-zero exit code. Successfully connected devices remain usable. See partial failures in multi-device commands for the full behavior.
Integrated one-command start
You can combine the orchestrator start with immediate device connection:
The orchestrator waits 5 seconds after startup before it attempts the auto-connect, to ensure local infrastructure is ready.
Reconnecting an existing session
If you disconnected a tunnel but the session is still running, re-running connect automatically detects the existing session and reconnects its tunnel:
You don’t need the --new-connection flag. The CLI checks for an existing session first and skips build and session creation if one is found.
Forcing a fresh session
To abandon the existing session and create a completely new one:
This stops the existing session first, freeing the device temporarily, then creates a new build and session. Use this when:
- The existing session is in an unknown or corrupted state.
- You want a clean device state.
- You’re starting a new test phase that requires fresh device state.
Feature limitations
Functional restrictions and missing capabilities in Device Tunnel CLI.
| Limitation | Detail |
|---|---|
| No Appium REST APIs | This is a direct-access solution; Appium-specific APIs are not available |
| No automated biometric toggles | Must be handled manually or via your own automation scripts |
| No automatic logging/video | Must capture logs and recordings explicitly in your scripts |
| No automatic time zone | Device timezone must be changed manually or via MDM |
| Max 100 concurrent tunnels | Per-orchestrator limit |
| Session lifetime | Sessions run for 2 hours maximum, and the device goes to cleanup when the maximum limit is reached |
Platform-specific limitations
Constraints specific to iOS, Android, or device naming conventions.
| Limitation | Detail |
|---|---|
| iOS platform | iOS tunnel uses socket mode (socket), so there is no numeric localPort. Use wdaPort instead |
--device-name with no platform |
Platform is auto-resolved via API call to dedicated_devices, which adds ~1s latency |
| Orchestrator port | The default port 8080 is hard-coded in the current build. Ensure it is free before starting |
Command behavior limitations
Command execution restrictions and default behavior constraints.
| Limitation | Detail |
|---|---|
| No built-in retry on tunnel PENDING | You must poll list-tunnels manually or script retries |
stop with no args |
Stops all sessions across all frameworks (both DEVICETUNNEL and APPIUM); use --device-id to scope |
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
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!