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 applications	Any service listening on the device's local network	The tunnel forwards the traffic, but the application itself is yours to provide: the service must already be running on the edge side, and you connect with your own client. WEDA does not ship or manage the edge-side application.

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: labels the intended service category for auditing and filtering. ssh, http, https, and mqtt are validated in WEDA v1.1.1; other values forward traffic but require you to supply the edge-side application and client. The default is ssh
• applicationHost: IP address or hostname reachable from the device's local network (use 127.0.0.1 for 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
• purpose and tags are 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, or RECONNECTING state can be terminated. Terminating from any other state returns 400
• The request body takes three fields: reason (human-readable explanation), graceful (when true, existing connections are closed cleanly; when false, the tunnel is terminated immediately), and forceTimeout (maximum seconds to wait for graceful closure before forcing it)
• forceTimeout only applies when graceful is true

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

Authentication

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

1. Confirm the firewall allows outbound connections to the Message Broker (4222/TLS) and Tunnel Server (443/WSS)
2. Confirm DNS resolves both endpoint hostnames
3. Check for a proxy or DPI device intercepting the WebSocket upgrade — proxies are not currently supported
4. 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

---

Last updated on Aug-1, 2026 | Version 1.1.1