CLI to SSH into an IoT edge device without Docker or localproxy. It implements the AWS IoT Secure Tunneling source WebSocket client in Node.js and runs a full SSH session over the tunnel with ssh2.
The edge device must run a destination-side tunnel agent — typically the Greengrass aws.greengrass.SecureTunneling component (or a custom equivalent) that starts localproxy in destination mode and forwards to SSH on port 22. This tool replaces only the client-sidelocalproxy; the device-side setup is unchanged.
How it works
End-to-end, the CLI wraps these steps:
Create tunnel — Call OpenTunnel via the AWS SDK, targeting the IoT thing name and requesting services (SSH, HTTP, HTTPS). AWS notifies the device over MQTT to start its destination localproxy.
Get source access token — OpenTunnel returns a sourceAccessToken (outbound connection credential for the client) and tunnelId.
Connect WebSocket — Open a WSS connection to data.tunneling.iot.<region>.amazonaws.com in source mode, passing the token in the access-token header and subprotocol aws.iot.securetunneling-3.0.
Create duplex stream — Wrap the WebSocket in TunnelStream, a Node.js Duplex that encodes/decodes v3 protobuf frames (SERVICE_IDS, STREAM_START, DATA, etc.). This replaces the TCP socket that source localproxy would expose on localhost.
Create SSH connection — Pass that stream to ssh2 as sock and run a normal SSH handshake and interactive shell over the tunneled byte stream.
On exit, the CLI closes the WebSocket and calls CloseTunnel.
Dependencies
Package
Role
@aws-sdk/client-iotsecuretunneling
OpenTunnel / CloseTunnel
ws
Source WebSocket to data.tunneling.iot.<region>.amazonaws.com
When developing from a clone, npm install then npx iotssh uses the local package (no publish required).
SSH authentication
The client only enables methods you configure:
Method
Config
Password
IOTSSH_PASSWORD or --password
Private key file
IOTSSH_KEY_PATH or --identity
ssh-agent
IOTSSH_USE_AGENT=1 or --use-agent
Keyboard-interactive
--try-keyboard (uses the same password for prompts)
If none are set, ssh2 may still try keys from your ssh-agent. Host key algorithms include legacy ssh-rsa for embedded SSH servers such as Dropbear.
File transfer
put and get open the same Secure Tunnel + SSH session, then use the SFTP subsystem (ssh2fastPut / fastGet). The device SSH server must support SFTP (OpenSSH does by default; some Dropbear builds do not).
Protocol note
Destination localproxy on the device still handles the device-side WebSocket and TCP bridge to SSH. This tool reimplements only the client-sidelocalproxy behavior (WebSocket + protobuf + stream bridge), as documented in V3WebSocketProtocolGuide.md.