Skip to main content
Run AI agents on remote machines via SSH instead of locally. This enables you to leverage powerful remote servers, access tools not installed on your local machine, or work with projects that must run in specific environments.

​
Overview

SSH Remote Execution wraps agent commands in SSH, executing them on a configured remote host while streaming output back to Maestro. Your local Maestro instance remains the control center, but the AI agent runs remotely. Use cases:
  • Run agents on a powerful cloud VM with more CPU/RAM
  • Access tools or SDKs installed only on specific servers
  • Work with codebases that require particular OS or architecture
  • Execute agents in secure/isolated environments

​
Configuring SSH Remotes

​
Adding a Remote Host

  1. Open Settings (Cmd+, / Ctrl+,)
  2. Scroll to the SSH Remote Hosts section under Remote Execution
  3. Click Add SSH Remote
  4. Configure the connection:
FieldDescription
NameDisplay name for this remote (e.g., “Dev Server”, “GPU Box”)
HostHostname or IP address (or SSH config Host pattern when using SSH config)
PortSSH port (default: 22)
UsernameSSH username for authentication (optional when using SSH config)
Private Key PathPath to your SSH private key (optional when using SSH config)
Remote Working DirectoryOptional default working directory on the remote host
Environment VariablesOptional key-value pairs to set on the remote
EnabledToggle to temporarily disable without deleting
  1. Click Test Connection to verify connectivity
  2. Click Save to store the configuration

​
Using SSH Config File

Maestro can import connection settings from your ~/.ssh/config file, making setup faster and more consistent with your existing SSH workflow.

​
Importing from SSH Config

When adding a new remote, Maestro automatically detects hosts defined in your SSH config:
  1. Click Add SSH Remote
  2. If SSH config hosts are detected, you’ll see an Import from SSH Config dropdown
  3. Select a host to auto-fill settings from your config
  4. The form shows “Using SSH Config” indicator when importing

​
How It Works

When using SSH config mode:
  • Host becomes the SSH config Host pattern (e.g., dev-server instead of 192.168.1.100)
  • Username and Private Key Path become optional—SSH inherits them from your config
  • Port defaults to your config’s value (only sent to SSH if overriding a non-default port)
  • You can still override any field to customize the connection
Example ~/.ssh/config: 
Host dev-server
    HostName 192.168.1.100
    User developer
    IdentityFile ~/.ssh/dev_key
    Port 2222

Host gpu-box
    HostName gpu.example.com
    User admin
    IdentityFile ~/.ssh/gpu_key
    ProxyJump bastion
With the above config, you can:
  1. Select “dev-server” from the dropdown
  2. Leave username/key fields empty (inherited from config)
  3. Optionally override specific settings
  4. Benefit from advanced features like ProxyJump for bastion hosts

​
Field Labels

When using SSH config mode, field labels indicate which values are optional:
  • Username (optional override) — leave empty to use SSH config’s User
  • Private Key Path (optional override) — leave empty to use SSH config’s IdentityFile

​
Clearing SSH Config Mode

To switch back to manual configuration:
  1. Click the × button next to “Using SSH Config” indicator
  2. Fill in all required fields manually

​
Connection Testing

Before saving, you can test your SSH configuration:
  • Basic test: Verifies SSH connectivity and authentication
  • Agent test: Checks if the AI agent command is available on the remote host
A successful test shows the remote hostname. Failed tests display specific error messages to help diagnose issues.

​
Setting a Global Default

Click the checkmark icon next to any remote to set it as the global default. When set:
  • All agents use this remote by default
  • Individual agents can override this setting
  • The default badge appears next to the remote name
Click the checkmark again to clear the default and return to local execution.

​
Per-Agent Configuration

Each agent can have its own SSH remote setting, overriding the global default.

​
Configuring an Agent

  1. Open the agent’s configuration panel (gear icon in session header, or via Settings → Agents)
  2. Find the SSH Remote dropdown
  3. Select an option:
OptionBehavior
Use Global DefaultFollows the global setting (shows which remote if one is set)
Force Local ExecutionAlways runs locally, ignoring any global default
[Specific Remote]Always uses this remote, regardless of global setting

​
Resolution Order

When spawning an agent, Maestro resolves which SSH remote to use:
  1. Per-agent explicit remote → Uses that specific remote
  2. Per-agent “Force Local” → Runs locally (ignores global)
  3. Per-agent “Use Global Default” → Falls through to global setting
  4. Global default set → Uses the global default remote
  5. No global default → Runs locally

​
Status Visibility

When a session is running via SSH remote:
  • The session displays the remote host name in the status area
  • Connection state reflects SSH connectivity
  • Errors are detected and displayed with SSH-specific context

​
Troubleshooting

​
Authentication Errors

ErrorSolution
”Permission denied (publickey)“Ensure your SSH key is added to the remote’s ~/.ssh/authorized_keys
”Host key verification failed”Add the host to known_hosts: ssh-keyscan hostname >> ~/.ssh/known_hosts
”Enter passphrase for key”Use a key without a passphrase, or add it to ssh-agent: ssh-add ~/.ssh/your_key

​
Connection Errors

ErrorSolution
”Connection refused”Verify SSH server is running on the remote host
”Connection timed out”Check network connectivity and firewall rules
”Could not resolve hostname”Verify the hostname/IP is correct
”No route to host”Check network path to the remote host

​
Agent Errors

ErrorSolution
”Command not found”Install the AI agent on the remote host
”Agent binary not found”Ensure the agent is in the remote’s PATH

​
Tips

  • Import from SSH config: Use the dropdown when adding remotes to import from ~/.ssh/config—saves time and keeps configuration consistent
  • Bastion hosts: Use ProxyJump in your SSH config for multi-hop connections; Maestro inherits this automatically
  • Key management: Use ssh-agent to avoid passphrase prompts
  • Keep-alive: Configure ServerAliveInterval in SSH config for long sessions
  • Test manually first: Verify ssh host 'claude --version' works before configuring in Maestro

​
Security Considerations

  • SSH keys should have appropriate permissions (chmod 600)
  • Use dedicated keys for Maestro if desired
  • Remote working directories should have appropriate access controls
  • Environment variables may contain sensitive data; they’re passed via SSH command line

​
Limitations

  • PTY (pseudo-terminal) features are not available over SSH
  • Some interactive agent features may behave differently
  • Network latency affects perceived responsiveness
  • The remote host must have the agent CLI installed and configured