Web SSH

Use Web SSH to access a device's SSH terminal from a browser. Your application creates and monitors a webssh Tunnel session, then opens the terminal page at the returned webSsh URL. WEDA provides the terminal page; your application supplies the session controls and entry link.

This walkthrough uses the same maintenance task as Tunnel Management: inspect inference-container logs on a remote device, then end the SSH login and close the Tunnel.

Note: API integration

WEDA Console does not currently provide a Web SSH entry. This guide is for integrating access into your own application. Confirm that browser-based SSH is available in your WEDA deployment with your WEDA administrator or support team before starting.

Before You Connect

Prepare the following:

• WEDA Node: Use an Activated, Connected Node and retain its Device ID. Replace the example ID, 74fe488d5d54, with your own.
• WEDA access: Prepare an access token for an identity with Admin access in the device's Org. Use it for the session APIs. See User Authentication for obtaining a token.
• SSH service: Confirm that the Node can reach the target host and SSH port. This example uses 192.168.10.50:22, representing the device's LAN IP and listening port. Replace them for your setup.
• Device account: Obtain an account accepted by the target SSH service. WEDA Admin access does not grant an SSH account or OS permissions.
• Network access: The Node needs outbound connectivity to your deployment's WEDA Cloud and Tunnel endpoints. The browser must be able to reach the returned Web SSH URL and use its terminal connection.

Two credentials serve different purposes:

Credential	Where it is used	What it authorizes
WEDA access token	Session API requests from your application	Create, inspect and terminate a Tunnel session
Device SSH account	The browser-based SSH sign-in	Access the target device's shell with that account's permissions

Open a Web SSH Session and Sign In

Use your deployment's API base URL for the session requests below.

1. Call Create Tunnel Session with serviceType: "webssh":

   POST /api/v1/devices/74fe488d5d54/tunnels/sessions
   Content-Type: application/json
   Authorization: Bearer YOUR_ACCESS_TOKEN
   
   {
     "serviceType": "webssh",
     "applicationHost": "192.168.10.50",
     "applicationPort": 22,
     "purpose": "Inspect inference container logs",
     "tags": ["ops", "diagnostics"]
   }

   All five fields are required. Choose a target host reachable from the Node and a listening port from 1 to 65535. The webssh label requests a browser entry; it does not install or enable SSH on the device.

2. Retain the returned tunnelSessionId. A 202 Accepted response confirms acceptance, not readiness.

3. Poll Get Session Details with that ID:

   GET /api/v1/devices/74fe488d5d54/tunnels/sessions/{tunnelSessionId}
   Authorization: Bearer YOUR_ACCESS_TOKEN

   Wait until sessionStatus is ESTABLISHED and webSsh contains a URL. The webSsh field is omitted until an endpoint has been allocated, and is not supplied for other service types. If the session reports FAILED or TERMINATED, inspect its termination information instead of continuing to wait.

4. Offer an Open terminal link or action in your application using the exact returned webSsh URL. Open it in a browser tab. Connect promptly because an unused Tunnel can be reclaimed.

   • Use webSsh, not tunnelEndpoint. The latter is the raw TCP endpoint used by a standard SSH client.
   • Do not construct the URL from the session ID or assume a fixed hostname, port or deployment prefix.
   • The browser entry, Open a Browser-Based SSH Session, returns an HTML page, not a JSON terminal API. Open the URL normally; do not append the WEDA access token or device credentials to it.

5. Authenticate using the device's SSH account when the browser or terminal page requests it. A new Tunnel session does not guarantee a fresh credential prompt; the browser may reuse authentication information.

Check the result: The terminal opens and the device accepts the SSH login. An established Tunnel alone does not confirm a successful device login.

Use the Terminal

Once signed in, use the terminal with the device account's permissions to inspect the relevant logs or perform your maintenance task. Web SSH does not grant root access or sudo privileges.

For your application's session controls:

• While waiting: Show the reported state and keep the terminal entry unavailable until the readiness conditions above are met.
• While connected: Retain the device and session IDs. Use Get Session Details to inspect connectivity or termination information if the terminal disconnects.
• After a disconnect: Query the session again and open the browser entry only when it is ESTABLISHED with a webSsh URL. RECONNECTING is reserved and unused in this version. A FAILED or TERMINATED session requires a new session when access is needed again.

The API's activeConns field counts client connections. It does not confirm SSH authentication or that a command succeeded. Check command output in the terminal for the result of your maintenance work.

See Tunnel Management for session states, automatic reclaim and lifetime limits. An open Tunnel does not override the device's SSH or shell idle policy.

Upload and Download Files

File upload and download use the Web SSH page's file panel over the SSH connection. The device's SSH service must have its SFTP subsystem enabled, and the SSH account must have permission to access the intended files.

Close the Session and Troubleshoot

1. End the device's shell session with exit when your work is complete. Closing the browser tab does not itself request Tunnel termination.

2. Call Terminate Session with the same device and session IDs:

   DELETE /api/v1/devices/74fe488d5d54/tunnels/sessions/{tunnelSessionId}
   Content-Type: application/json
   Authorization: Bearer YOUR_ACCESS_TOKEN
   
   {
     "reason": "Inference container inspection complete",
     "graceful": true,
     "forceTimeout": 30
   }

   This requests graceful closure, with up to 30 seconds before forcing closure. A 202 response accepts the request.

3. Query the session detail until it reports TERMINATED. If it is already terminating, closed or failed, refresh its detail rather than repeatedly sending DELETE.

Check the result: The SSH login has ended and the Tunnel reports TERMINATED.

Use the failing layer to choose the next check:

Observation	Check next
Session API returns 401 or 403	Check the WEDA token and Admin access in the device's Org.
Session never becomes ready	Check Node connectivity, target SSH reachability and the session's termination details. Do not open the browser entry before both readiness conditions are met.
Browser entry returns 401 or rejects the SSH login	Check the device's SSH credentials and permitted authentication method. A browser-entry authentication challenge is separate from the WEDA session API token.
Browser entry returns 404	Refresh session details. Check that it is an existing webssh session with an allocated endpoint and a current webSsh URL.
Browser entry returns 502	The Web SSH service could not be reached. Provide the session ID and attempt time to your WEDA support team.
Page loads, but the terminal does not connect	Check browser network access to the terminal service and the Node's access to the target SSH service. Include the browser's connection error when requesting support.
Terminal disconnects	Query the session state and termination reason. Check device-side SSH policies and Tunnel limits before creating another session.
File transfer fails	Check SFTP availability, the account's file permissions and the destination path.

When requesting support, include the Device ID, session ID, attempt time, reported state and available error or termination details.