SSH/SFTP Operations Tool

ByteBuddy provides powerful remote server management capabilities through the built-in remote_command_execution tool that supports SSH/SFTP operations, enabling seamless server operations directly from your development environment.

Session Usage Examples

Direct SSH Tool Usage in Chat

Users can directly request SSH operations in chat:

"Please check disk usage and service status on production-web-01 server"

tools:
  - name: "server-health-check"
    tool: "remote_command_execution"
    args:
      serverName: "production-web-01"
      username: "admin"
      keyPath: "${SSH_KEY_PATH}"
      commands:
        - "df -h"
        - "systemctl status nginx"
        - "systemctl status docker"
        - "free -h"

Using with Configuration Files

Create a configuration file .bytebuddy/tools.yaml in your project to predefine common server connections:

tools:
  - name: "prod-web"
    tool: "remote_command_execution"
    args:
      serverName: "production-web-01"
      username: "admin"
      keyPath: "${SSH_KEY_PATH}"

  - name: "staging-db"
    tool: "remote_command_execution"
    args:
      serverName: "staging-db-01"
      username: "dbadmin"
      keyPath: "${SSH_KEY_PATH}"

Then reference these pre-configured tools in chat:

"Use the prod-web tool to check our web server load"

tools:
  - name: "load-check"
    tool: "remote_command_execution"
    args:
      serverName: "production-web-01"
      username: "admin"
      keyPath: "${SSH_KEY_PATH}"
      commands:
        - "uptime"
        - "top -bn1 | head -20"

File Transfer Session Example

"Please upload the deployment script to staging-server and set execution permissions"

tools:
  - name: "deploy-script-upload"
    tool: "remote_command_execution"
    args:
      serverName: "staging-server"
      username: "deployer"
      keyPath: "${SSH_KEY_PATH}"
      uploadFiles:
        - localPath: "./scripts/deploy.sh"
          remotePath: "/tmp/deploy.sh"
          permissions: "755"
      commands:
        - "chmod +x /tmp/deploy.sh"
        - "ls -la /tmp/deploy.sh"

Tool Overview

🔐 Secure Authentication

• SSH Key Authentication: Support for RSA, ECDSA, Ed25519 keys
• Password Authentication: Secure password-based authentication
• SSH Config Support: Automatically reads ~/.ssh/config for predefined connections
• Multiple Authentication Methods: Flexible fallback between auth methods

🚀 Command Execution

• Batch Commands: Execute multiple commands in a single session
• Real-time Output: Live command output streaming
• Timeout Protection: Configurable timeouts prevent hanging operations
• Security Validation: Built-in command security evaluation

📁 File Operations

• File Upload: Secure file upload with permission control
• File Download: Download remote files to local system
• Directory Operations: Recursive directory operations
• File Size Limits: Configurable size limits for safety

⚡ Performance Optimizations

• Connection Pooling: Reuse SSH connections for better performance
• Idle Connection Cleanup: Automatic cleanup of idle connections
• Connection Statistics: Monitor connection pool status

Tool Usage Methods

Calling Through Chat Interface

In the chat interface, you can directly ask the AI assistant to perform SSH operations:

Please check disk usage and service status on production-server

The AI assistant will automatically call the remote_command_execution tool to perform the operations.

Direct Tool Invocation

You can also define tool calls directly in configuration:

tools:
  - name: "system-check"
    tool: "remote_command_execution"
    args:
      serverName: "dev-server"
      username: "developer"
      commands:
        - "uname -a"
        - "df -h"
        - "free -h"
        - "ps aux | head -10"

Tool Parameters

Basic Parameters

Parameter	Type	Required	Description
serverName	string	Yes	Server hostname or IP address
username	string	No	SSH username
port	number	No	SSH port (default: 22)
password	string	No	SSH password (prefer key auth)
keyPath	string	No	Path to SSH private key file

Command Execution Parameters

Parameter	Type	Description
commands	array	Array of commands to execute on remote server
timeout	number	Command execution timeout in seconds (default: 30)
captureOutput	boolean	Whether to capture and return command output (default: true)

File Operation Parameters

Parameter	Type	Description
uploadFiles	array	Array of files to upload to remote server
downloadFiles	array	Array of files to download from remote server
maxFileSize	number	Maximum file size in bytes for operations (default: 104857600 = 100MB)
reuseConnection	boolean	Whether to reuse existing SSH connections (default: true)

File Upload/Download Structure

Upload Files:

uploadFiles:
  - localPath: "/path/to/local/file"
    remotePath: "/path/to/remote/file"
    permissions: "644" # Optional

Download Files:

downloadFiles:
  - remotePath: "/path/to/remote/file"
    localPath: "/path/to/local/file"

Configuration Methods

Method 1: Using SSH Config File

Configure servers in ~/.ssh/config:

# ~/.ssh/config
Host dev-server
    HostName dev.example.com
    User developer
    Port 22
    IdentityFile ~/.ssh/id_rsa

Host prod-server
    HostName production.example.com
    User admin
    Port 2222
    IdentityFile ~/.ssh/prod_key
    StrictHostKeyChecking no

Then use hostnames directly in tool calls:

tools:
  - name: "production-check"
    tool: "remote_command_execution"
    args:
      serverName: "prod-server" # Reference Host from SSH config
      commands:
        - "uptime"
        - "df -h"

Method 2: Explicit Parameter Configuration

tools:
  - name: "explicit-connection"
    tool: "remote_command_execution"
    args:
      serverName: "192.168.1.100"
      username: "admin"
      port: 2222
      keyPath: "/path/to/private/key"
      commands:
        - "whoami"
        - "pwd"

Practical Usage Examples

1. System Monitoring

tools:
  - name: "system-monitor"
    tool: "remote_command_execution"
    args:
      serverName: "web-server"
      username: "ops"
      commands:
        # System load
        - "uptime"
        # Disk usage
        - "df -h"
        # Memory usage
        - "free -h"
        # Network connections
        - "ss -tuln"
        # Top processes
        - "top -bn1 | head -20"

2. Log Analysis

tools:
  - name: "log-analyzer"
    tool: "remote_command_execution"
    args:
      serverName: "app-server"
      username: "admin"
      commands:
        # Find error logs
        - "tail -100 /var/log/application.log | grep ERROR"
        # Count fatal errors
        - "grep -c 'FATAL' /var/log/application.log"
        # View recent logs
        - "journalctl -u myapp --since '1 hour ago'"

3. Configuration Deployment

tools:
  - name: "config-deployer"
    tool: "remote_command_execution"
    args:
      serverName: "web-server"
      username: "admin"
      uploadFiles:
        - localPath: "./configs/nginx.conf"
          remotePath: "/etc/nginx/nginx.conf"
          permissions: "644"
        - localPath: "./configs/app.env"
          remotePath: "/opt/myapp/.env"
          permissions: "600"
      commands:
        # Test configuration
        - "nginx -t"
        # Reload service
        - "systemctl reload nginx"
        # Check service status
        - "systemctl status nginx"

4. File Backup

tools:
  - name: "backup-manager"
    tool: "remote_command_execution"
    args:
      serverName: "db-server"
      username: "admin"
      uploadFiles:
        - localPath: "./scripts/backup.sh"
          remotePath: "/opt/scripts/backup.sh"
          permissions: "755"
      commands:
        # Execute backup script
        - "bash /opt/scripts/backup.sh"
        # List backup files
        - "ls -la /backups/"
      downloadFiles:
        - remotePath: "/backups/latest.tar.gz"
          localPath: "./backups/db-backup-$(date +%Y%m%d).tar.gz"

Advanced Usage

1. Connection Pooling Optimization

tools:
  - name: "pooled-connection"
    tool: "remote_command_execution"
    args:
      serverName: "cluster-node"
      username: "admin"
      reuseConnection: true # Enable connection reuse
      timeout: 60 # Increase timeout
      commands:
        - "hostname"
        - "docker ps"

2. Custom Authentication

tools:
  - name: "custom-auth"
    tool: "remote_command_execution"
    args:
      serverName: "secure-server"
      username: "special-user"
      keyPath: "/path/to/special/key"
      port: 2222
      commands:
        - "whoami"
        - "groups"

3. Timeout and Retry Configuration

tools:
  - name: "robust-operation"
    tool: "remote_command_execution"
    args:
      serverName: "unstable-server"
      username: "admin"
      timeout: 120 # Increase timeout
      commands:
        - "long-running-task"

Security Best Practices

1. Authentication Security

• Prefer SSH keys over passwords
• Use different keys for different environments
• Rotate keys regularly
• Limit user permissions

2. Command Security

• Avoid dangerous commands like rm -rf /
• Use absolute paths instead of relative paths
• Validate command output
• Set appropriate timeouts

3. File Operation Security

• Limit file sizes
• Validate file paths
• Set appropriate permissions
• Avoid uploading sensitive files

Troubleshooting

Common Issues

Connection Failed

Solutions:
1. Check server address and port
2. Verify SSH configuration
3. Confirm network connectivity
4. Check firewall settings

Authentication Failed

Solutions:
1. Verify username and key
2. Check key permissions (chmod 600)
3. Confirm SSH agent status
4. Check SSH verbose logs

Command Timeout

Solutions:
1. Increase timeout parameter value
2. Optimize command execution efficiency
3. Check server load
4. Consider batch execution

With the remote_command_execution tool, you can securely and efficiently manage remote servers, achieving automated operations.