Manages distributed workloads and file sharing across Tailscale SSH-connected machines. Automates remote command execution, intelligent load balancing, file synchronization workflows, host health monitoring, and multi-machine orchestration using sshsync. Activates when discussing remote machines, Tailscale SSH, workload distribution, file sharing, or multi-host operations.
npx claudepluginhub human-frontier-labs-inc/human-frontier-labs-marketplace --plugin tailscale-sshsync-agentThis skill uses the workspace's default tool permissions.
This skill automatically activates when you need to:
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
This skill automatically activates when you need to:
โ Distribute workloads across multiple machines
โ Share files between Tailscale-connected hosts
โ Execute commands remotely across host groups
โ Monitor machine availability and health
โ Automate multi-machine workflows
This agent provides intelligent workload distribution and file sharing management across Tailscale SSH-connected machines using the sshsync CLI tool.
Core Architecture:
Key Features:
What is sshsync?
sshsync is a Python CLI tool for managing SSH connections and executing operations across multiple hosts. It provides:
Installation:
pip install sshsync
Configuration:
sshsync uses two configuration sources:
~/.ssh/config): Host connection details~/.config/sshsync/config.yaml): Group assignmentsExample SSH Config:
Host homelab-1
HostName 100.64.1.10
User admin
IdentityFile ~/.ssh/id_ed25519
Host prod-web-01
HostName 100.64.1.20
User deploy
Port 22
Example sshsync Config:
groups:
homelab:
- homelab-1
- homelab-2
production:
- prod-web-01
- prod-web-02
- prod-db-01
development:
- dev-laptop
- dev-desktop
sshsync Commands Used:
| Command | Purpose | Example |
|---|---|---|
sshsync all | Execute on all hosts | sshsync all "df -h" |
sshsync group | Execute on group | sshsync group web "systemctl status nginx" |
sshsync push | Push files to hosts | sshsync push --group prod ./app /var/www/ |
sshsync pull | Pull files from hosts | sshsync pull --host db /var/log/mysql ./logs/ |
sshsync ls | List hosts | sshsync ls --with-status |
sshsync sync | Sync ungrouped hosts | sshsync sync |
What is Tailscale?
Tailscale is a zero-config VPN that creates a secure network between your devices. It provides:
machine-name.tailnet-name.ts.net)Tailscale SSH:
Tailscale includes SSH functionality that works seamlessly with standard SSH:
# Standard SSH via Tailscale
ssh user@machine-name
# Tailscale-specific SSH command
tailscale ssh machine-name
Integration with sshsync:
Since Tailscale SSH uses standard SSH protocol, it works perfectly with sshsync. Just configure your SSH config with Tailscale hostnames:
Host homelab-1
HostName homelab-1.tailnet.ts.net
User admin
Tailscale Commands Used:
| Command | Purpose | Example |
|---|---|---|
tailscale status | Show network status | Lists all connected machines |
tailscale ping | Check connectivity | tailscale ping machine-name |
tailscale ssh | SSH to machine | tailscale ssh user@machine |
User Query: "Which of my machines are online?"
Workflow:
sshsync ls --with-statusImplementation: scripts/sshsync_wrapper.py โ get_host_status()
Output Format:
๐ข homelab-1 (homelab) - Online - Tailscale: Connected
๐ข prod-web-01 (production, web-servers) - Online - Tailscale: Connected
๐ด dev-laptop (development) - Offline - Last seen: 2h ago
๐ข prod-db-01 (production, databases) - Online - Tailscale: Connected
Summary: 3/4 hosts online (75%)
User Query: "Run this task on the least loaded machine"
Workflow:
uptime or top)free or vm_stat)df)Implementation: scripts/load_balancer.py โ select_optimal_host()
Load Score Calculation:
score = (cpu_pct * 0.4) + (mem_pct * 0.3) + (disk_pct * 0.3)
Lower score = better candidate for task execution.
Output Format:
โ Selected host: prod-web-02
Reason: Lowest load score (0.32)
- CPU: 15% (vs avg 45%)
- Memory: 30% (vs avg 60%)
- Disk: 40% (vs avg 55%)
Executing: npm run build
[Task output...]
โ Completed in 2m 15s
User Query: "Sync my code to all development machines"
Workflow:
Implementation: scripts/sshsync_wrapper.py โ push_to_group()
Supported Operations:
--recurseOutput Format:
๐ค Syncing: ~/projects/myapp โ /var/www/myapp
Group: development (3 hosts)
Preview (dry-run):
- dev-laptop: 145 files, 12.3 MB
- dev-desktop: 145 files, 12.3 MB
- dev-server: 145 files, 12.3 MB
Execute? [Proceeding...]
โ dev-laptop: Synced 145 files in 8s
โ dev-desktop: Synced 145 files in 6s
โ dev-server: Synced 145 files in 10s
Summary: 3/3 successful (435 files, 36.9 MB total)
User Query: "Check disk space on all web servers"
Workflow:
Implementation: scripts/sshsync_wrapper.py โ execute_on_group()
Features:
Output Format:
๐ง Executing on group 'web-servers': df -h /var/www
web-01:
Filesystem: /dev/sda1
Size: 100G, Used: 45G, Available: 50G (45% used)
web-02:
Filesystem: /dev/sda1
Size: 100G, Used: 67G, Available: 28G (67% used) โ ๏ธ
web-03:
Filesystem: /dev/sda1
Size: 100G, Used: 52G, Available: 43G (52% used)
โ ๏ธ Alert: web-02 is above 60% disk usage
User Query: "Deploy to staging, test, then production"
Workflow:
Stage 1 - Staging Deploy:
Stage 2 - Validation:
Stage 3 - Production Deploy:
Stage 4 - Verification:
Implementation: scripts/workflow_executor.py โ deploy_workflow()
Output Format:
๐ Multi-Stage Deployment Workflow
Stage 1: Staging Deployment
โ Pushed code to staging-01
โ Build completed (2m 15s)
โ Tests passed (145/145)
Stage 2: Validation
โ Health check passed
โ Database migration OK
โ Smoke tests passed (12/12)
Stage 3: Production Deployment
โ prod-web-01: Deployed & verified
โ prod-web-02: Deployed & verified
โ prod-web-03: Deployed & verified
Stage 4: Verification
โ All health checks passed
โ No errors in logs (5min window)
โ
Deployment completed successfully in 12m 45s
Purpose: Python wrapper around sshsync CLI for programmatic access
Functions:
get_host_status(group=None): Get online/offline status of hostsexecute_on_all(command, timeout=10, dry_run=False): Run command on all hostsexecute_on_group(group, command, timeout=10, dry_run=False): Run on specific groupexecute_on_host(host, command, timeout=10): Run on single hostpush_to_hosts(local_path, remote_path, hosts=None, group=None, recurse=False, dry_run=False): Push filespull_from_host(host, remote_path, local_path, recurse=False, dry_run=False): Pull fileslist_hosts(with_status=True): List all configured hostsget_groups(): Get all defined groups and their membersadd_hosts_to_group(group, hosts): Add hosts to a groupUsage Example:
from sshsync_wrapper import execute_on_group, push_to_hosts
# Execute command
result = execute_on_group(
group="web-servers",
command="systemctl status nginx",
timeout=15
)
# Push files
push_to_hosts(
local_path="./dist",
remote_path="/var/www/app",
group="production",
recurse=True
)
Purpose: Tailscale-specific operations and status management
Functions:
get_tailscale_status(): Get Tailscale network status (all peers)check_connectivity(host): Ping host via Tailscaleget_peer_info(hostname): Get detailed info about peerlist_online_machines(): List all online Tailscale machinesget_machine_ip(hostname): Get Tailscale IP for machinevalidate_tailscale_ssh(host): Check if Tailscale SSH is workingUsage Example:
from tailscale_manager import get_tailscale_status, check_connectivity
# Get network status
status = get_tailscale_status()
print(f"Online machines: {status['online_count']}")
# Check specific host
is_online = check_connectivity("homelab-1")
Purpose: Intelligent task distribution based on machine resources
Functions:
get_machine_load(host): Get CPU, memory, disk metricscalculate_load_score(metrics): Calculate composite load scoreselect_optimal_host(candidates, prefer_group=None): Pick best hostget_group_capacity(): Get aggregate capacity of groupdistribute_tasks(tasks, hosts): Distribute multiple tasks optimallyUsage Example:
from load_balancer import select_optimal_host
# Find best machine for task
best_host = select_optimal_host(
candidates=["web-01", "web-02", "web-03"],
prefer_group="production"
)
# Execute on selected host
execute_on_host(best_host, "npm run build")
Purpose: Common multi-machine workflow automation
Functions:
deploy_workflow(code_path, staging_group, prod_group): Full deployment pipelinebackup_workflow(hosts, backup_paths, destination): Backup from multiple hostssync_workflow(source_host, target_group, paths): Sync from one to manyrolling_restart(group, service_name): Zero-downtime service restarthealth_check_workflow(group, endpoint): Check health across groupUsage Example:
from workflow_executor import deploy_workflow, backup_workflow
# Deploy with testing
deploy_workflow(
code_path="./dist",
staging_group="staging",
prod_group="production"
)
# Backup from all databases
backup_workflow(
hosts=["db-01", "db-02"],
backup_paths=["/var/lib/mysql"],
destination="./backups"
)
Purpose: Common utilities and formatting functions
Functions:
format_bytes(bytes): Human-readable byte formatting (1.2 GB)format_duration(seconds): Human-readable duration (2m 15s)parse_ssh_config(): Parse ~/.ssh/config for host detailsparse_sshsync_config(): Parse sshsync group configurationget_timestamp(): Get ISO timestamp for loggingsafe_execute(func, *args, **kwargs): Execute with error handlingvalidate_path(path): Check if path exists and is accessiblePurpose: Validate user inputs and parameters
Functions:
validate_host(host, valid_hosts=None): Validate host existsvalidate_group(group, valid_groups=None): Validate group existsvalidate_path_exists(path): Check local path existsvalidate_timeout(timeout): Ensure timeout is reasonablevalidate_command(command): Basic command safety validationPurpose: Validate host configuration and availability
Functions:
validate_ssh_config(host): Check host has SSH config entryvalidate_host_reachable(host, timeout=5): Check host is reachablevalidate_group_members(group): Ensure group has valid membersget_invalid_hosts(hosts): Find hosts without valid configPurpose: Validate SSH and Tailscale connections
Functions:
validate_ssh_connection(host): Test SSH connection worksvalidate_tailscale_connection(host): Test Tailscale connectivityvalidate_ssh_key(host): Check SSH key authenticationget_connection_diagnostics(host): Comprehensive connection testingFunction: analyze_host_availability(group=None)
Objective: Determine which machines are online and accessible
Inputs:
group (optional): Specific group to check (None = all hosts)Outputs:
{
'total_hosts': 10,
'online_hosts': 8,
'offline_hosts': 2,
'availability_pct': 80.0,
'by_group': {
'production': {'online': 3, 'total': 3, 'pct': 100.0},
'development': {'online': 2, 'total': 3, 'pct': 66.7},
'homelab': {'online': 3, 'total': 4, 'pct': 75.0}
},
'offline_hosts_details': [
{'host': 'dev-laptop', 'last_seen': '2h ago', 'groups': ['development']},
{'host': 'homelab-4', 'last_seen': '1d ago', 'groups': ['homelab']}
]
}
Interpretation:
Function: analyze_load_distribution(group=None)
Objective: Understand resource usage across machines
Inputs:
group (optional): Specific group to analyzeOutputs:
{
'hosts': [
{
'host': 'web-01',
'cpu_pct': 45,
'mem_pct': 60,
'disk_pct': 40,
'load_score': 0.49,
'status': 'moderate'
},
# ... more hosts
],
'aggregate': {
'avg_cpu': 35,
'avg_mem': 55,
'avg_disk': 45,
'total_capacity': 1200 # GB
},
'recommendations': [
{
'host': 'web-02',
'issue': 'High CPU usage (85%)',
'action': 'Consider migrating workloads'
}
]
}
Load Status:
Function: analyze_sync_status(local_path, remote_path, group)
Objective: Compare local files with remote versions
Inputs:
local_path: Local directory to compareremote_path: Remote directory pathgroup: Group to checkOutputs:
{
'local_files': 145,
'local_size': 12582912, # bytes
'hosts': [
{
'host': 'web-01',
'status': 'in_sync',
'files_match': 145,
'files_different': 0,
'missing_files': 0
},
{
'host': 'web-02',
'status': 'out_of_sync',
'files_match': 140,
'files_different': 3,
'missing_files': 2,
'details': ['config.json modified', 'index.html modified', ...]
}
],
'sync_percentage': 96.7,
'recommended_action': 'Push to web-02'
}
Function: analyze_network_latency(hosts=None)
Objective: Measure connection latency to hosts
Inputs:
hosts (optional): Specific hosts to test (None = all)Outputs:
{
'hosts': [
{'host': 'web-01', 'latency_ms': 15, 'status': 'excellent'},
{'host': 'web-02', 'latency_ms': 45, 'status': 'good'},
{'host': 'db-01', 'latency_ms': 150, 'status': 'fair'}
],
'avg_latency': 70,
'min_latency': 15,
'max_latency': 150,
'recommendations': [
{'host': 'db-01', 'issue': 'High latency', 'action': 'Check network path'}
]
}
Latency Classification:
Function: comprehensive_infrastructure_report(group=None)
Objective: One-stop function for complete infrastructure overview
Inputs:
group (optional): Limit to specific group (None = all)Outputs:
{
'report_timestamp': '2025-10-19T19:43:41Z',
'group': 'production', # or 'all'
'metrics': {
'availability': {...}, # from analyze_host_availability
'load_distribution': {...}, # from analyze_load_distribution
'network_latency': {...}, # from analyze_network_latency
'tailscale_status': {...} # from Tailscale integration
},
'summary': "Production infrastructure: 3/3 hosts online, avg load 45%, network latency 35ms",
'alerts': [
"โ web-02: High CPU usage (85%)",
"โ db-01: Elevated latency (150ms)"
],
'recommendations': [
"Consider rebalancing workload from web-02",
"Investigate network path to db-01"
],
'overall_health': 'good' # excellent | good | fair | poor
}
Overall Health Classification:
Error: Cannot connect to host
Causes:
Handling:
try:
execute_on_host("web-01", "ls")
except ConnectionError as e:
# Try Tailscale ping first
if not check_connectivity("web-01"):
return {
'error': 'Host unreachable',
'suggestion': 'Check Tailscale connection',
'diagnostics': get_connection_diagnostics("web-01")
}
# Then check SSH
if not validate_ssh_connection("web-01"):
return {
'error': 'SSH authentication failed',
'suggestion': 'Check SSH keys: ssh-add -l'
}
Error: Operation timed out
Causes:
Handling:
Error: File sync failed
Causes:
Handling:
Error: Invalid parameter
Examples:
Handling:
Parameter Validation:
host = validate_host(host, valid_hosts=get_all_hosts())
group = validate_group(group, valid_groups=get_groups())
timeout = validate_timeout(timeout)
Connection Validation:
if not validate_host_reachable(host, timeout=5):
raise ConnectionError(f"Host {host} is not reachable")
Path Validation (for file operations):
if not validate_path_exists(local_path):
raise ValueError(f"Path does not exist: {local_path}")
Result Validation:
report = validate_operation_result(result)
if report.has_critical_issues():
raise OperationError(report.get_summary())
State Verification: Confirm operation succeeded
Logging: Record all operations for audit trail
Host Status Cache:
Load Metrics Cache:
Group Configuration Cache:
Parallel Execution:
Connection Pooling:
Lazy Loading:
Progressive Results:
This skill automatically activates when you mention:
Hosts & Machines:
Tools:
Operations:
Groups:
Actions:
Monitoring:
Workflows:
User: "Which of my Tailscale machines are online?"
Agent Response:
Checking Tailscale network status...
๐ข homelab-1 (homelab) - Online - Tailscale: Connected
IP: 100.64.1.10 | Latency: 15ms
๐ข homelab-2 (homelab) - Online - Tailscale: Connected
IP: 100.64.1.11 | Latency: 18ms
๐ด dev-laptop (development) - Offline
Last seen: 2 hours ago | Tailscale: Not connected
๐ข prod-web-01 (production, web-servers) - Online - Tailscale: Connected
IP: 100.64.1.20 | Latency: 25ms
๐ข prod-db-01 (production, databases) - Online - Tailscale: Connected
IP: 100.64.1.30 | Latency: 30ms
Summary: 4/5 hosts online (80%)
Average latency: 22ms
User: "Check disk space on all web servers"
Agent Response:
Executing on group 'web-servers': df -h /var/www
๐ง web-01:
Filesystem: /dev/sda1
Size: 100G | Used: 45G | Available: 50G (45% used)
Status: โ Healthy
๐ง web-02:
Filesystem: /dev/sda1
Size: 100G | Used: 67G | Available: 28G (67% used)
Status: โ Warning - Above 60%
๐ง web-03:
Filesystem: /dev/sda1
Size: 100G | Used: 52G | Available: 43G (52% used)
Status: โ Healthy
โ ๏ธ Alert: web-02 is above 60% disk usage
Recommendation: Clear old logs or increase disk space
User: "Run this npm build on the machine with most available resources"
Agent Response:
Analyzing resource availability across 5 machines...
Load Analysis:
web-01: CPU 45%, Mem 60%, Disk 40% โ Score: 0.49 (moderate)
web-02: CPU 85%, Mem 70%, Disk 65% โ Score: 0.75 (high load)
web-03: CPU 20%, Mem 35%, Disk 30% โ Score: 0.28 (low load) โ
โ Selected: web-03
Reason: Lowest load score (0.28)
Available: CPU 80%, Memory 65%, Disk 70%
Executing on web-03: npm run build
[Build output...]
โ Build completed successfully
Duration: 2m 15s
Output: ./dist (145 files, 12.3 MB)
Final load: CPU 65%, Mem 50% (still below average)
User: "Push my app directory to all production servers"
Agent Response:
๐ค Syncing: ~/projects/myapp โ /var/www/myapp
Target group: production (3 hosts)
Analyzing source...
145 files, 12.3 MB total
Preview (dry-run):
prod-web-01: 145 files โ /var/www/myapp
prod-web-02: 145 files โ /var/www/myapp
prod-db-01: Skipped (not in web-servers group)
Checking target capacity...
โ prod-web-01: 50 GB available
โ prod-web-02: 28 GB available
Executing push...
โ prod-web-01: Synced 145 files in 8.2s
Modified: 12 files
Added: 3 files
โ prod-web-02: Synced 145 files in 6.5s
Modified: 12 files
Added: 3 files
Summary: 2/2 successful (290 files, 24.6 MB total)
User: "Deploy this to staging, run tests, then push to production"
Agent Response:
๐ Multi-Stage Deployment Workflow
Stage 1: Staging Deployment
๐ค Pushing to staging-01...
โ Code synced (145 files, 12.3 MB) - 8s
๐จ Running build...
$ npm run build
โ Build completed - 2m 15s
๐งช Running tests...
$ npm test
โ All tests passed (145/145) - 45s
Stage 2: Staging Validation
โ Health endpoint: 200 OK
โ Database migrations: Up to date
โ Smoke tests: 12/12 passed
Stage 3: Production Deployment
Rolling deployment to 3 hosts...
โณ prod-web-01:
โ Code synced
โ Build completed
โ Service restarted gracefully
โ Health check passed
Duration: 3m 10s
โณ prod-web-02:
โ Code synced
โ Build completed
โ Service restarted gracefully
โ Health check passed
Duration: 3m 5s
โณ prod-web-03:
โ Code synced
โ Build completed
โ Service restarted gracefully
โ Health check passed
Duration: 3m 12s
Stage 4: Production Verification
โ All health checks passed (3/3)
โ No errors in logs (5min window)
โ Response times normal (avg 45ms)
โ
Deployment completed successfully!
Total duration: 12m 45s
Hosts updated: 3
Zero downtime: โ
User: "Give me a complete status report of my infrastructure"
Agent Response:
๐ Infrastructure Report
Generated: 2025-10-19 19:43:41
=== AVAILABILITY ===
Total Hosts: 10
Online: 8 (80%)
Offline: 2
By Group:
production: 3/3 (100%) โ
development: 2/3 (66.7%) โ
homelab: 3/4 (75%)
Offline Hosts:
โข dev-laptop (development) - Last seen: 2h ago
โข homelab-4 (homelab) - Last seen: 1d ago
=== LOAD DISTRIBUTION ===
Average Load: 45% CPU, 55% Memory, 45% Disk
Top 3 Loaded Hosts:
1. web-02: 85% CPU, 70% Mem, 65% Disk (Score: 0.75) โ
2. db-01: 60% CPU, 75% Mem, 55% Disk (Score: 0.65)
3. web-01: 45% CPU, 60% Mem, 40% Disk (Score: 0.49)
Top 3 Available Hosts:
1. web-03: 20% CPU, 35% Mem, 30% Disk (Score: 0.28) โ
2. homelab-1: 25% CPU, 40% Mem, 35% Disk (Score: 0.33)
3. homelab-2: 30% CPU, 45% Mem, 40% Disk (Score: 0.38)
=== NETWORK LATENCY ===
Average: 35ms
Range: 15ms - 150ms
Excellent (< 50ms): 6 hosts
Good (50-100ms): 1 host
Fair (100-200ms): 1 host (db-01: 150ms) โ
=== TAILSCALE STATUS ===
Network: Connected
Peers Online: 8/10
Exit Node: None
MagicDNS: Enabled
=== ALERTS ===
โ web-02: High CPU usage (85%) - Consider load balancing
โ db-01: Elevated latency (150ms) - Check network path
โ dev-laptop: Offline for 2 hours - May need attention
=== RECOMMENDATIONS ===
1. Rebalance workload from web-02 to web-03
2. Investigate network latency to db-01
3. Check status of dev-laptop and homelab-4
4. Consider scheduling maintenance for web-02
Overall Health: GOOD โ
See INSTALLATION.md for detailed setup instructions.
Quick start:
# 1. Install sshsync
pip install sshsync
# 2. Configure SSH hosts
vim ~/.ssh/config
# 3. Sync host groups
sshsync sync
# 4. Install agent
/plugin marketplace add ./tailscale-sshsync-agent
# 5. Test
"Which of my machines are online?"
Current version: 1.0.0
See CHANGELOG.md for release history.
See DECISIONS.md for detailed rationale behind tool selection, architecture choices, and trade-offs considered.