SSH Tunnel Plugin

The SSH Tunnel plugin opens and maintains a persistent SSH port-forward to a fixed remote server (localhost:<local_port> → <server_ip>:<remote_port>), with automatic reconnection if the tunnel drops. It is infrastructural: no agent tools, no UI.

Only one tunnel is managed per Codumentor server process.

Requirements

OpenSSH client (ssh) on PATH
An SSH private key at ssh_key_path, or one of:
~/.ssh/id_rsa
~/.ssh/id_ed25519
~/.ssh/datacrunch_key

Configuration

plugins:
  - module: codumentor.plugins.ssh_tunnel
    class: SSHTunnelPlugin
    args:
      server_ip: "192.168.1.100"
      remote_port: 1248
      local_port: 1248
      enabled: true

Parameter	Type	Default	Description
`server_ip`	string	(required)	IP address of the remote server
`remote_port`	int	`1248`	Port on the remote server
`local_port`	int	`1248`	Port to bind on localhost
`ssh_key_path`	string	`None`	Path to the SSH private key. If unset, auto-detects from the locations above
`check_interval_seconds`	int	`30`	How often to check that the tunnel is still forwarding
`ssh_user`	string	`"root"`	Remote SSH username
`enabled`	bool	`true`	Disable without removing the plugin from config

Behaviour

On startup the plugin checks whether local_port is listening and whether an HTTP GET to http://127.0.0.1:<local_port>/ actually forwards (any HTTP response counts). A healthy existing tunnel is adopted — including one started by another Codumentor instance on the same host. A listening port that does not forward is treated as a zombie: the stale process is killed and a new tunnel is created (ssh -f -N -L …).

A background loop repeats that check every check_interval_seconds and reconnects on failure. Tunnel failure is non-fatal: a warning is logged and the loop keeps retrying.

On shutdown, only a tunnel this process created is stopped. Adopted tunnels are left running so other Codumentor instances keep using them.

Security and ops notes

Host key verification is disabled (StrictHostKeyChecking=no, UserKnownHostsFile=/dev/null).
SSH keepalive is ServerAliveInterval=60 and ServerAliveCountMax=3 (drop after ~180 s of unresponsiveness).
Typical pairing: LLM Server with the DataCrunch backend, which expects the model on localhost:1248.