Remote Access — Tunnel
Overview
A Tunnel is an on-demand reverse port-forwarding session that lets you reach TCP-based services available to a WEDA Node without opening an inbound firewall port or configuring a VPN on the device's network.
When you request a tunnel session, WEDA Node initiates an outbound connection to the WEDA tunnel service. WEDA then forwards traffic from the assigned tunnel endpoint to the customer-specified application host and port. The target can be a service on the WEDA Node itself or another host reachable from the device's local network.
Target Services
WEDA Tunnel forwards TCP traffic according to the application host and port specified by the customer. This allows it to reach a broad range of services without requiring the tunnel to understand the application protocol.
| Example | Typical target | Notes |
|---|---|---|
| SSH | An SSH service on the WEDA Node or local network | Connect with a standard SSH client and authenticate with an account configured on the target SSH service. |
| HTTP or HTTPS | A web dashboard or REST service | TLS, when used, is handled by the target service. |
| MQTT | An MQTT broker reachable from the device | Connect with an MQTT client through the assigned tunnel host and port. |
| Other TCP services | A customer-specified host and port | Availability depends on the target service and the serviceType values supported by the WEDA release. |
Session States
| State | Description |
|---|---|
REQUESTED | Session created; WEDA Cloud is instructing WEDA Node to establish the tunnel |
ESTABLISHING | WEDA Node is opening the reverse WebSocket connection |
ESTABLISHED | Tunnel is active; the endpoint is ready to accept connections |
RECONNECTING | Brief disconnection detected; WEDA Node is automatically reconnecting |
TERMINATING | Termination in progress |
TERMINATED | Session closed normally |
FAILED | The session failed to establish, reconnect, or terminate; inspect its health and termination details |
The detail response also includes healthStatus (HEALTHY, DEGRADED, UNHEALTHY, or
UNKNOWN) and, when applicable, terminationSource and terminationReason.
Operations
| Operation | API | Description |
|---|---|---|
| Create Tunnel Session | POST /api/v1/devices/{deviceId}/tunnels/sessions | Create and start a new tunnel session |
| List Tunnel Sessions | GET /api/v1/devices/{deviceId}/tunnels/sessions | List tunnel sessions, with optional status, service type, tag, pagination, and sorting filters |
| Get Session Details | GET /api/v1/devices/{deviceId}/tunnels/sessions/{tunnelSessionId} | Get details and current state of a session |
| Terminate Session | DELETE /api/v1/devices/{deviceId}/tunnels/sessions/{tunnelSessionId} | Request graceful or immediate termination of a tunnel session |
Constraints
Creating a session
- Device must be online and registered
serviceType: identifies the intended service category; use a value supported by the WEDA releaseapplicationHost: IP address or hostname reachable from the device's local network (use127.0.0.1for services on the device itself)applicationPort: integer 1–65535- No other ports are blocked or reserved — including ports below 1024 — as long as the target service is actually listening there
purposeandtagsare required — used for auditing and filtering
Session lifetime
- Connection timeout: If no client connects within 120 seconds after creation, the session closes automatically
- Maximum lifetime: The session closes 3600 seconds (1 hour) after creation, regardless of activity
Terminating a session
- Sessions in
REQUESTED,ESTABLISHING,ESTABLISHED, orRECONNECTINGstate can be terminated - Graceful termination allows existing connections to close cleanly before the tunnel closes
- Set
forceTimeoutto a reasonable value (e.g. 30 seconds) to bound the graceful shutdown window
Concurrency
- There is currently no limit on the number of tunnel sessions per device, user, or organization
- Overall concurrent tunnels are still bounded by the Tunnel Server's shared capacity
The tunnel provides network access to the target service; it does not replace that service's
authentication. For example, SSH credentials and the resulting user, root, or sudo privileges
remain under the control of the target device's SSH service.
Network Requirements
WEDA Node initiates two outbound connections — it never listens for inbound traffic:
| Requirement | Detail |
|---|---|
| Outbound destinations | A Message Broker endpoint (control channel) and a Tunnel Server endpoint (data channel). Both are provided to the device at provisioning time, not hardcoded — the exact hostname varies by environment |
| Outbound ports / protocol | Control channel: TCP/4222 over TLS. Tunnel data channel: typically 443 (WSS — WebSocket over TLS). No inbound ports are required |
| DNS resolution | Required — both endpoints are normally provided as hostnames |
| HTTP/HTTPS proxy | Not supported. The device does not read HTTP_PROXY / HTTPS_PROXY / NO_PROXY, and the tunnel client has no proxy configuration. Allow the device to connect outbound directly, or use a transparent proxy / L4 firewall rule — a standard forward proxy will not work |
| SaaS vs. on-premises | Endpoint addresses differ by deployment (on-premises uses your own broker/tunnel server addresses), but the protocol and port pattern are the same |
| Tunnel Server address stability | The Tunnel Server URL is supplied per session by WEDA Cloud and is not fixed on the device — it can vary by environment or which server is assigned |
| IP allowlisting | Allowlist by FQDN/domain, not by IP — the Tunnel Server address can change, and the platform aims to keep the destination stable at the domain level |
If the Tunnel Service Is Unreachable
The POST call still returns 202, and the session progresses REQUESTED → ESTABLISHING. If it
doesn't establish within the session's timeout, or exhausts its reconnect attempts, the session
transitions to FAILED with terminationReason describing the cause — the failure surfaces
through session status, not as an error on the original request.
Troubleshooting Checklist
- Confirm the firewall allows outbound connections to the Message Broker (4222/TLS) and Tunnel Server (443/WSS)
- Confirm DNS resolves both endpoint hostnames
- Check for a proxy or DPI device intercepting the WebSocket upgrade — proxies are not currently supported
- Confirm the target service (
applicationHost:applicationPort) is actually listening on the device's local network
Network-level failures typically surface as session status FAILED.
Scenario
A field engineer needs terminal access to a WEDA Node on a factory floor network to investigate a container issue:
The engineer connects to the host and port in tunnelEndpoint with a standard SSH client and
authenticates with an account configured on the target SSH service. No inbound firewall rule or
VPN is required on the device's network.
Related
- Device must be online to create a tunnel: Device Management
- Run commands on containers after connecting: Container Deployment & Commands
- Postman walkthrough: Remote Access Tunnel