Codumentor logo Codumentor

SSH Tunnel Plugin

The SSH Tunnel Plugin auto-opens and maintains a persistent SSH port-forward tunnel to a fixed remote server, with automatic reconnection on failure. It runs as an infrastructural background service — it does not register agent tools or event bus handlers.

Overview

The SSH Tunnel plugin:

  1. Establishes an SSH tunnel at server startup (priority 1) that forwards localhost:<local_port> → <server_ip>:<remote_port>
  2. Runs a background maintenance loop that checks tunnel health every 30 seconds and reconnects if the tunnel drops
  3. Uses a module-level singleton so only the first instantiation does real work; subsequent instantiations are zero-cost no-ops

Requirements

Configuration

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

Configuration Parameters

ParameterTypeDefaultDescription
server_ipstring(required)IP address of the remote server
remote_portint1248Port on the remote server
local_portint1248Port to bind on localhost
ssh_key_pathstringNonePath to SSH private key. If unset, auto-detects from ~/.ssh/id_rsa, ~/.ssh/id_ed25519, or ~/.ssh/datacrunch_key
check_interval_secondsint30How often the maintenance loop checks tunnel health
ssh_userstring"root"Remote SSH username
enabledbooltrueDisable the plugin without removing it from config

How It Works

Tunnel Establishment

On registration, the plugin checks if local_port is already listening. If so, it assumes the tunnel is already up and skips creation. Otherwise it kills any stale SSH tunnel processes to the target IP and creates a fresh tunnel via ssh -f -N -L <local_port>:localhost:<remote_port>.

Maintenance Loop

After registration, a background asyncio.Task loops every check_interval_seconds:

Singleton Behaviour

The first SSHTunnelPlugin instance created becomes the owner — it manages the tunnel and the maintenance task. Every subsequent instance (e.g., per-conversation instantiations in the agent) detects the existing owner and skips all setup work. Cleanup is idempotent: only the owner cancels the maintenance task and kills tunnel processes.

Notes