directvt/vtm v2025.12.03

on GitHub

Changes

• Fix dtvt session closing when process creation failed (empty frozen grey window).
• Update /doc/architecture.md (Remote Access using socat/winsocat over SSH Reverse Tunnel).
  Note: vtm has the ability to fully deserialize/serialize its state through arbitrary channels (like socat over ssh reverse tunnel) and does not require a running ssh server on the remote side. For example, this makes it easy to get interactive access to GithubActions runner on any platform.

Remote Access using socat/winsocat over SSH Reverse Tunnel

Notes:

• The remote and local sides may differ in platform.
• Using the localhost name may cause connection issues with the IP address family (IPv4: 127.0.0.1 vs. IPv6: [::1]) between remote systems. Use an explicit IP address to avoid this.

Unix

• Remote side

  #   Run reverse tunnel for 1122tcp in background
  #                         ┌─ relay all traffic passed through 127.0.0.1:1122tcp to the remote host
  #                ─────────┴────
    ssh -N -R 1122:127.0.0.1:1122 user@1.2.3.4 &
  #     ─┬ ─┬─────                ─┬────────── ┬
  #      │  └─ listen on remote    │           └─ run in background
  #      │                         └─ remote host
  #      └─ do nothing on remote just listen 1122tcp
  #
  # Save the background process'' PID
  ssh_tunnel_pid=$!
  #
  # Run vtm and forward its stdio (in dtvt format) streams to 127.0.0.1:1122
  #            ┌──────< relay dtvt-stream <─────┐      ┌─ kill the ssh reverse tunnel after vtm exits
  #       ─────┴────────────────────────       ─┴─   ──┴─────────────────
    socat tcp-listen:1122,bind=127.0.0.1 exec:"vtm"; kill $ssh_tunnel_pid
  #       ─────┬────────────────────────
  #            └─ wait for forwarded connections on 127.0.0.1:1122tcp
  # or reversed
  # socat exec:"vtm" tcp-listen:1122,bind=127.0.0.1; kill $ssh_tunnel_pid

• Local side with ip=1.2.3.4 (connect to the remote vtm desktop via 127.0.0.1:1122tcp)

  #    ┌──────────< binary DirectVT <─────────────┐
  # ───┴───────                          ─────────┴─────
    vtm -r dtvt socat tcp:127.0.0.1:1122 stdin\!\!stdout
  #                   ────┬───────────── ─────────┬─────
  #                       └─> relay dtvt-stream >─┘

Windows

• Install winsocat:

  winget install winsocat
  

• Remote side

  # Run reverse tunnel for 1122tcp in background.
  $process = Start-Process "ssh" "-N -R 1122:127.0.0.1:1122 user@1.2.3.4" -PassThru -WindowStyle Minimized
  # Run vtm and forward its stdio streams to 127.0.0.1:1122.
  #               ┌──────< relay dtvt-stream <─────┐      ┌─ kill the ssh reverse tunnel after vtm exits
  #          ─────┴────────────────────────       ─┴─   ──┴─────────────────────────
    winsocat tcp-listen:1122,bind=127.0.0.1 exec:"vtm"; Stop-Process -Id $process.Id
  #          ─────┬────────────────────────
  #               └─ wait for forwarded connections on 127.0.0.1:1122tcp
  # or
  # winsocat exec:"vtm" tcp-listen:1122,bind=127.0.0.1; Stop-Process -Id $process.Id

• Local side with ip=1.2.3.4 (connect to the remote vtm desktop via 127.0.0.1:1122tcp)

  #    ┌───────< binary DirectVT <─────────────┐
  # ───┴───────                             ───┴─
    vtm -r dtvt winsocat tcp:127.0.0.1:1122 stdio
  #                      ┬───────────────── ───┬─
  #                      └> relay dtvt-stream >┘
  # Kill the abandoned winsocat process (it keeps running for some reason)
  Get-Process -Name "winsocat" | Stop-Process -Force