Remote Execution Connector

The Remote Execution connector allows Agentcy to execute commands and transfer files on remote hosts via SSH. It provides 3 live tools for running commands, uploading files, and downloading files.

Authentication

The connector authenticates via SSH using either password or private key authentication.

{
  "name": "Production Server",
  "source_type": "remote_execution",
  "config": {
    "host": "server.example.com",
    "port": 22,
    "username": "deploy",
    "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n..."
  }
}

Variable	Required	Description
host	Yes	Remote host address (IP or hostname)
port	No	SSH port (default: 22)
username	Yes	SSH username
password	One of	SSH password (use private_key instead when possible)
private_key	One of	SSH private key (PEM format)
timeout_secs	No	Connection and command timeout in seconds

WARNING

Store private keys and passwords as secrets. Avoid committing credentials in plain text. Use a dedicated service account with the minimum required permissions.

Live Tools (3)

Tool	Description	Arguments
remote_exec_command	Execute a shell command on the remote host	command, cwd?, env?, timeout?
remote_exec_upload	Upload a file to the remote host	local_content, remote_path, mode?
remote_exec_download	Download a file from the remote host	remote_path

Example: Agent Using Remote Execution Tools

User: "Check disk usage on the production server"

Agent: I'll run a disk check on the server.
→ Calls remote_exec_command(command: "df -h")
→ Returns: "Filesystem      Size  Used Avail Use% Mounted on
  /dev/sda1       100G   72G   28G  72% /
  /dev/sdb1       500G  410G   90G  82% /data"
→ Reports: "Production server disk usage: root partition at 72%, data partition at 82%.
  The /data partition may need attention soon."

User: "Upload the new config file"

Agent: I'll upload the configuration.
→ Calls remote_exec_upload(local_content: "...", remote_path: "/etc/app/config.yaml", mode: "0644")
→ Returns: "File uploaded to /etc/app/config.yaml"

ETL Ingestion

This connector does not support ETL ingestion. All tools operate as live SSH interactions with the remote host.

Configuration Reference

{
  "name": "Production Server",
  "source_type": "remote_execution",
  "config": {
    "host": "server.example.com",
    "port": 22,
    "username": "deploy",
    "password": null,
    "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
    "timeout_secs": 30
  }
}

Field	Type	Default	Description
host	string	required	Remote host address
port	number	22	SSH port
username	string	required	SSH username
password	string	--	SSH password
private_key	string	--	SSH private key (PEM format)
timeout_secs	number	30	Connection and command timeout

Troubleshooting

Error	Cause	Fix
Connection refused	SSH service not running or port blocked	Verify SSH is running and port 22 (or custom port) is open
Authentication failed	Invalid credentials	Check username, password, or private key
Host key verification failed	Unknown host key	Add the host key to known_hosts or verify the host fingerprint
Permission denied	User lacks permission for the command or path	Use a user with appropriate sudo or file permissions
Command timeout	Command exceeded timeout	Increase timeout_secs or run long commands with nohup
Connection timed out	Host is unreachable	Verify network connectivity and firewall rules