SSH Remote Execution

Fresh

Run AI agents on remote machines via SSH, streaming output back to Maestro.

Configuration

Settings → SSH Hosts → Add:

Field	Description
Name	Display name for the host
Host	Hostname or IP address
Port	SSH port (default: 22)
Username	SSH login user
Private Key Path	Path to SSH private key
Remote Working Directory	Default directory on remote
Environment Variables	KEY=VALUE pairs for remote sessions
Enabled	Toggle on/off

Import from SSH Config

Maestro auto-detects hosts from ~/.ssh/config. Select from dropdown to auto-fill. Supports ProxyJump for bastion hosts automatically.

Connection Multiplexing

Maestro respects SSH config directives:

• ControlMaster — Reuse existing connections
• ControlPath — Socket file location
• ControlPersist — Keep connection alive

Hardware Keys

Connection multiplexing is recommended for YubiKey/hardware key users to avoid repeated touches.

Testing

Click "Test Connection" to verify:

1. SSH connectivity to the remote host
2. AI agent availability on the remote machine

Per-Session Configuration

When creating a new agent, use the "SSH Remote Execution" dropdown to select Local or a specific remote host.

Remote Identification

Indicator	Location
"REMOTE" pill	Next to session in Left Bar
Host name badge	Main Panel header
Agent type	Shows "claude-code (SSH)"

Full Remote Capabilities

Everything works on remote:

• File Explorer browsing remote filesystem
• Auto Run executing on remote projects
• Git Worktrees on remote repositories
• Command Terminal executing on remote host (full PTY)
• Group Chat participation alongside local agents

Troubleshooting

Error	Fix
Permission denied (publickey)	Add key to ~/.ssh/authorized_keys on remote
Host key verification failed	ssh-keyscan hostname >> ~/.ssh/known_hosts
Enter passphrase for key	Add to agent: ssh-add ~/.ssh/your_key

See Also

• Remote Agent Workflow — End-to-end guide
• Group Chat — Remote agents in Group Chat