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 so the agent can run commands and transfer files on remote hosts via SSH/SFTP.

asyncssh is a Codumentor dependency (already in requirements.txt).

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
      idle_timeout: 60
      max_connections_per_session: 5
      known_hosts_path: ./data/ssh_known_hosts
      hosts:
        prod-server:
          hostname: 192.168.1.10
          port: 22
          username: deploy
          key_path: ~/.ssh/id_rsa
          host_key_policy: known_hosts
        lab:
          hostname: lab.example.com
          username: ubuntu
          host_key_policy: trust_first

Plugin parameters

Parameter	Type	Default	Description
enabled	bool	true	Enable or disable the plugin
target_agents	string	"main"	Which agents get the tools: "main", "subagent", or "all"
allow_adhoc	bool	true	Allow connections to hosts not listed in hosts
default_timeout	int	30	Default ssh_exec 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 pooled connections after this many seconds
max_connections_per_session	int	5	Maximum pooled connections per conversation
known_hosts_path	string	./data/ssh_known_hosts	OpenSSH-format file used when a host's host_key_policy is trust_first

Per-host parameters (args.hosts.<alias>)

Parameter	Type	Default	Description
hostname	string	(required)	Hostname or IP
port	int	22	SSH port
username	string	"root"	SSH username
key_path	string	None	Private key file. If unset, default keys / ssh-agent are used
host_key_policy	string	"known_hosts"	"known_hosts" (system known_hosts), "trust_first" (TOFU into known_hosts_path), or "disabled" (no verification). Unknown values fall back to "known_hosts".

Tools

ssh_exec

Parameter	Required	Description
host	Yes	Pre-configured alias, or hostname/IP when ad-hoc is allowed
command	Yes	Shell command to run
username	No	Ad-hoc username (pre-configured hosts use their config)
key_path	No	Ad-hoc private key path
port	No	Ad-hoc SSH port (default 22)
timeout	No	Command timeout in seconds

ssh_upload / ssh_download

Parameter	Required	Description
host	Yes	Alias or hostname/IP
local_path	Yes	Path on the Codumentor server
remote_path	Yes	Path on the remote host
username / key_path / port	No	Same ad-hoc overrides as ssh_exec

Host key verification

Default (host_key_policy: known_hosts) uses the system OpenSSH known_hosts files. The first connection to an unknown host fails until that host is in those files.

trust_first records the host key in known_hosts_path on first connect and verifies it afterwards (TOFU). A later key mismatch prompts the user to accept or reject. disabled skips verification entirely.

User settings

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

• Enable Remote SSH — turn off all SSH tools for their account
• Allow ad-hoc connections — restrict their account to pre-configured hosts even if the server allows ad-hoc

Notes

• Connections are pooled per conversation and closed when the session ends, or after idle_timeout.
• Auth is key-based (configured key, default keys, or agent). Password/passphrase prompts are not wired in the UI.