SSH Remote Operations

Execute commands and transfer files on remote servers securely via SSH.

Overview

This skill provides three main capabilities:

1. Remote Command Execution - Run commands on remote servers
2. File Transfers - Upload/download files via SCP
3. Multi-Host Operations - Execute commands across multiple servers in parallel or sequentially

All operations use secure authentication (SSH agent, key files, or passwords) via environment variables, ensuring credentials are never read into context.

Quick Start

Basic Setup

Set connection credentials via environment variables:

export SSH_HOST=example.com
export SSH_USER=deploy
export SSH_KEY_PATH=~/.ssh/id_rsa  # Optional, uses SSH agent if not set

Execute Commands

# Run a single command
python3 scripts/ssh_exec.py "systemctl status nginx"

# Run command sequence
python3 scripts/ssh_exec.py "cd /var/www && git pull && sudo systemctl restart app"

# Get JSON output for parsing
python3 scripts/ssh_exec.py "df -h" --json

Transfer Files

# Upload file
python3 scripts/scp_transfer.py upload local.txt /remote/path/file.txt

# Download file
python3 scripts/scp_transfer.py download /remote/logs/app.log ./local-logs/

# Upload directory recursively
python3 scripts/scp_transfer.py upload dist/ /var/www/app/ --recursive

Multi-Host Operations

# Execute on multiple hosts
export SSH_HOSTS="web1.example.com web2.example.com web3.example.com"
python3 scripts/ssh_multi.py "systemctl status nginx"

# Sequential execution (one at a time)
python3 scripts/ssh_multi.py "systemctl restart app" --sequential

# Use host list file
python3 scripts/ssh_multi.py "uptime" --hosts-file servers.txt

Common Operations

System Administration

Check system status:

# Disk usage
python3 scripts/ssh_exec.py "df -h"

# Memory usage
python3 scripts/ssh_exec.py "free -h"

# Service status
python3 scripts/ssh_exec.py "systemctl status nginx"

# View logs
python3 scripts/ssh_exec.py "sudo journalctl -u nginx -n 50"

Application Deployment

Deploy application:

# Pull and restart
python3 scripts/ssh_exec.py "
    cd /var/www/app &&
    git pull origin main &&
    npm install &&
    npm run build &&
    sudo systemctl restart app
"

# Upload build artifacts
python3 scripts/scp_transfer.py upload dist/ /var/www/app/dist/ --recursive

# Rolling deployment across cluster
python3 scripts/ssh_multi.py "
    cd /var/www/app &&
    git pull &&
    npm install &&
    sudo systemctl reload nginx
" --hosts-file web-servers.txt --sequential

Log Management

Fetch and analyze logs:

# Get recent errors
python3 scripts/ssh_exec.py "tail -n 100 /var/log/app/error.log | grep ERROR"

# Download logs for local analysis
python3 scripts/scp_transfer.py download /var/log/nginx/access.log ./logs/

# Search across multiple servers
python3 scripts/ssh_multi.py "grep 'ERROR' /var/log/app/error.log | tail -n 10" \
    --hosts-file web-servers.txt

Database Operations

Backup and restore:

# Create PostgreSQL backup
python3 scripts/ssh_exec.py "sudo -u postgres pg_dump mydb > /backup/mydb-$(date +%Y%m%d).sql"

# Download backup
python3 scripts/scp_transfer.py download "/backup/mydb-*.sql" ./backups/

# Restore from backup
python3 scripts/scp_transfer.py upload backup.sql /tmp/
python3 scripts/ssh_exec.py "sudo -u postgres psql mydb < /tmp/backup.sql"

Docker Management

Manage containers:

# List containers
python3 scripts/ssh_exec.py "docker ps"

# View logs
python3 scripts/ssh_exec.py "docker logs --tail 100 myapp"

# Restart container
python3 scripts/ssh_exec.py "docker restart myapp"

# Deploy with docker-compose
python3 scripts/scp_transfer.py upload docker-compose.yml /opt/app/
python3 scripts/ssh_exec.py "cd /opt/app && docker-compose up -d"

Authentication Methods

SSH Agent (Recommended) ⭐

Most secure - keys managed by ssh-agent, never exposed:

# Start ssh-agent and add key
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

# Use skill normally - ssh-agent handles authentication
export SSH_HOST=example.com
export SSH_USER=deploy
python3 scripts/ssh_exec.py "uptime"

Key File Path

Secure - scripts only pass path to ssh command, never read key:

export SSH_HOST=example.com
export SSH_USER=deploy
export SSH_KEY_PATH=~/.ssh/id_rsa
python3 scripts/ssh_exec.py "uptime"

Password Authentication ⚠️

Less secure - requires sshpass utility:

export SSH_HOST=example.com
export SSH_USER=deploy
export SSH_PASSWORD='your-password'
python3 scripts/ssh_exec.py "uptime"

Security Note: SSH agent is most secure. Key files are second best. Passwords should only be used when keys are not available.

WSL2 Support

When running in WSL2 (Windows Subsystem for Linux), this skill automatically detects the environment and uses the Windows version of ssh.exe and scp.exe instead of the Ubuntu versions. This is essential for proper integration with Windows-based SSH agents like 1Password.

How It Works

1. Automatic Detection - The scripts detect WSL2 by checking /proc/version for "microsoft" or "wsl"
2. Windows SSH Resolution - Uses which ssh.exe to find the Windows SSH executable from your Windows PATH
3. Path Conversion - Automatically converts WSL Unix paths (like /home/user/.ssh/id_rsa) to Windows WSL network paths (like \\wsl$\Ubuntu\home\user\.ssh\id_rsa)
4. Transparent Operation - All existing commands work exactly the same way

1Password Integration

This WSL2 support enables seamless 1Password SSH agent integration:

# In WSL2, this automatically uses Windows ssh.exe
# which connects to 1Password's SSH agent running on Windows
export SSH_HOST=example.com
export SSH_USER=deploy
python3 scripts/ssh_exec.py "uptime"

Requirements

• WSL2 (not WSL1)
• Windows OpenSSH installed (usually at C:\Windows\System32\OpenSSH\ssh.exe)
• 1Password SSH agent enabled in Windows (if using 1Password)

Verification

To verify WSL2 detection is working:

# Check if running in WSL2
cat /proc/version  # Should contain "microsoft" or "WSL"

# Check if Windows ssh.exe is found
which ssh.exe      # Should show path like /mnt/c/Windows/System32/OpenSSH/ssh.exe

Fallback Behavior

If Windows SSH executables are not found, the scripts automatically fall back to using the standard Unix ssh and scp commands.

Configuration Options

Environment Variables

Primary configuration method:

• SSH_HOST - Remote hostname or IP (required)
• SSH_USER - SSH username (required)
• SSH_PORT - SSH port (default: 22)
• SSH_KEY_PATH - Path to private key file
• SSH_PASSWORD - SSH password (not recommended)
• SSH_HOSTS - Multiple hosts for ssh_multi.py (comma or space-separated)

Command-Line Arguments

Override environment variables:

python3 scripts/ssh_exec.py "uptime" \
    --host example.com \
    --user deploy \
    --port 22 \
    --key-path ~/.ssh/id_rsa \
    --timeout 300

SSH Config File

Use ~/.ssh/config for host aliases:

Host prod-web
    HostName web.production.example.com
    User deploy
    Port 22
    IdentityFile ~/.ssh/prod_key

Then use the alias:

export SSH_HOST=prod-web
export SSH_USER=deploy
python3 scripts/ssh_exec.py "uptime"

Environment Profiles

Create separate config files per environment:

# .env.production
SSH_HOST=prod.example.com
SSH_USER=deploy
SSH_KEY_PATH=~/.ssh/prod_key

# .env.staging
SSH_HOST=staging.example.com
SSH_USER=deploy
SSH_KEY_PATH=~/.ssh/staging_key

# Load and use
source .env.production
python3 scripts/ssh_exec.py "systemctl status nginx"

Multi-Host Patterns

Parallel Execution

Execute on all hosts simultaneously (default):

python3 scripts/ssh_multi.py "uptime" \
    --hosts "web1.example.com web2.example.com web3.example.com"

Sequential Execution

Execute one host at a time (for rolling updates):

python3 scripts/ssh_multi.py "systemctl restart app" \
    --hosts-file web-servers.txt \
    --sequential

Host List Files

Create files with one host per line:

# web-servers.txt
web1.example.com
web2.example.com
web3.example.com

Use with commands:

python3 scripts/ssh_multi.py "df -h" --hosts-file web-servers.txt

Different Credentials Per Host

Specify user and key per host:

# Format: host:user:key_path
python3 scripts/ssh_multi.py "uptime" \
    --hosts "host1.com:user1:~/.ssh/key1,host2.com:user2:~/.ssh/key2"

Script Reference

ssh_exec.py

Execute commands on remote host.

Usage:

python3 scripts/ssh_exec.py <command> [options]

Options:

• --host - Remote hostname
• --user - SSH username
• --port - SSH port
• --key-path - Path to private key
• --password - SSH password
• --timeout - Command timeout in seconds (default: 300)
• --json - Output results as JSON

Examples: See references/examples.md

scp_transfer.py

Transfer files to/from remote host.

Usage:

python3 scripts/scp_transfer.py <upload|download> <source> <destination> [options]

Options:

• --host - Remote hostname
• --user - SSH username
• --port - SSH port
• --key-path - Path to private key
• --password - SSH password
• -r, --recursive - Recursively copy directories

Examples: See references/examples.md

ssh_multi.py

Execute commands on multiple hosts.

Usage:

python3 scripts/ssh_multi.py <command> [options]

Options:

• --hosts - Space or comma-separated list of hosts
• --hosts-file - File containing host list
• --user - Default SSH username
• --port - SSH port
• --key-path - Default path to SSH private key
• --password - Default SSH password
• --sequential - Execute sequentially instead of parallel
• --max-workers - Max parallel workers (default: 10)
• --timeout - Command timeout per host (default: 300)
• --json - Output results as JSON

Examples: See references/examples.md

Security Considerations

Critical Security Principles:

1. Private keys are NEVER read by these scripts - only paths are passed to SSH commands
2. Use SSH agent when possible - most secure authentication method
3. Environment variables for credentials - never hardcode passwords or keys
4. Never commit .env files - add to .gitignore immediately

Key file permissions:

chmod 600 ~/.ssh/id_rsa     # Private key
chmod 644 ~/.ssh/id_rsa.pub # Public key
chmod 700 ~/.ssh            # SSH directory

For detailed security guidance: See references/security.md

Detailed Documentation

For comprehensive guides and examples:

• references/security.md - Authentication methods, security best practices, credential protection
• references/config.md - Connection setup, environment variables, SSH config, multi-environment management
• references/examples.md - Common use cases including deployments, monitoring, log analysis, database operations, Docker management

Troubleshooting

Connection Issues

# Test basic connectivity
python3 scripts/ssh_exec.py "echo 'Connection successful'"

# Check key permissions
ls -la ~/.ssh/id_rsa  # Should be -rw------- (600)
chmod 600 ~/.ssh/id_rsa

# Verify key is in authorized_keys on remote
python3 scripts/ssh_exec.py "cat ~/.ssh/authorized_keys | grep '$(ssh-keygen -y -f ~/.ssh/id_rsa)'"

Permission Denied

Usually means:

• Wrong username or key
• Key not in authorized_keys on remote
• Key file permissions incorrect (must be 600)

Password Authentication Not Working

Requires sshpass:

# Ubuntu/Debian
sudo apt-get install sshpass

# macOS
brew install sshpass

Timeout Errors

Increase timeout for long-running commands:

python3 scripts/ssh_exec.py "apt-get update && apt-get upgrade -y" --timeout 1800

Tips

• Use JSON output for parsing results: --json
• Set timeouts for long operations: --timeout 600
• Sequential for safety during updates: --sequential
• Test on one host first before using ssh_multi.py
• Use SSH config for complex setups (bastion hosts, jump hosts)
• Environment files make it easy to switch between environments