Remote SSH Plugin

Experimental — This plugin is under active development. APIs and behavior may change in future releases.

The Remote SSH Plugin registers ssh_exec, ssh_upload, and ssh_download tools that allow the agent to run commands and transfer files on remote hosts via SSH/SFTP.

Overview

The Remote SSH plugin:

Registers three tools: ssh_exec (execute shell commands), ssh_upload (SFTP upload), ssh_download (SFTP download)
Maintains a per-session connection pool with configurable idle timeout and keepalive
Uses Trust On First Use (TOFU) host key verification, stored in an OpenSSH-format known hosts file
Supports pre-configured named host aliases and ad-hoc connections to arbitrary hosts

Requirements

The Python package asyncssh must be installed:

pip install asyncssh

Configuration

Basic Configuration

plugins:
  - module: codumentor.plugins.remote_ssh
    class: RemoteSSHPlugin
    args:
      enabled: true
      allow_adhoc: true         # Allow connecting to hosts not in 'hosts' map (default: true)
      default_timeout: 30       # Command timeout in seconds (default: 30)
      max_output_size: 10240    # Max output bytes per tool call (default: 10240)

Pre-Configured Hosts

Define named hosts to avoid specifying connection details on each call:

plugins:
  - module: codumentor.plugins.remote_ssh
    class: RemoteSSHPlugin
    args:
      hosts:
        prod-server:
          hostname: 192.168.1.10
          port: 22
          username: deploy
          key_filename: ~/.ssh/id_rsa
        dev-server:
          hostname: dev.example.com
          username: developer

Full Configuration

plugins:
  - module: codumentor.plugins.remote_ssh
    class: RemoteSSHPlugin
    args:
      enabled: true
      target_agents: "main"
      allow_adhoc: true
      default_timeout: 30
      max_output_size: 10240
      keepalive_interval: 30          # SSH keepalive in seconds (default: 30)
      idle_timeout: 60                # Close idle connections after N seconds (default: 60)
      max_connections_per_session: 5  # Max pooled connections per session (default: 5)
      known_hosts_path: ./data/ssh_known_hosts  # TOFU host key store path
      hosts:
        my-server:
          hostname: 10.0.0.5
          username: ubuntu

Configuration Parameters

Parameter	Type	Default	Description
`enabled`	bool	`true`	Enable/disable the plugin
`target_agents`	string	`"main"`	Which agents get the tools (`"main"`, `"subagent"`, `"all"`)
`allow_adhoc`	bool	`true`	Allow connections to hosts not in the `hosts` map
`default_timeout`	int	`30`	Default command execution timeout (seconds)
`max_output_size`	int	`10240`	Maximum output size per tool call (bytes)
`keepalive_interval`	int	`30`	SSH keepalive interval (seconds)
`idle_timeout`	int	`60`	Close idle connections after N seconds of inactivity
`max_connections_per_session`	int	`5`	Maximum pooled connections per conversation session
`known_hosts_path`	string	`./data/ssh_known_hosts`	Path to the TOFU known hosts file (OpenSSH format)

Tools

`ssh_exec`

Execute a shell command on a remote host.

Parameter	Required	Description
`host`	Yes	Hostname/IP or pre-configured alias
`command`	Yes	Shell command to run
`username`	No	SSH username (overrides config)
`timeout`	No	Command timeout in seconds

`ssh_upload`

Upload a local file to a remote host via SFTP.

Parameter	Required	Description
`host`	Yes	Hostname/IP or pre-configured alias
`local_path`	Yes	Source file path on the Codumentor server
`remote_path`	Yes	Destination path on the remote host
`username`	No	SSH username

`ssh_download`

Download a file from a remote host via SFTP.

Parameter	Required	Description
`host`	Yes	Hostname/IP or pre-configured alias
`remote_path`	Yes	Source path on the remote host
`local_path`	Yes	Destination path on the Codumentor server
`username`	No	SSH username

Host Key Verification (TOFU)

On the first connection to a new host, the plugin records the host's public key in known_hosts_path (OpenSSH format). Subsequent connections verify against the stored key, providing protection against MITM attacks after initial trust is established.

User Settings

Users can override two settings via the Web UI (Settings → Remote SSH):

Enable Remote SSH — Disable all SSH tools for their account
Allow ad-hoc connections — Restrict their account to pre-configured hosts only, regardless of server config

Notes

Connection pool sweeps run lazily on first use and automatically clean up idle/expired connections
Session connections are closed when the conversation session ends
All plugin instances share a class-level registry for coordinated shutdown on server stop