Connect a Machine

SSH connections are reusable connection profiles for remote development in Emdash. Remote projects use them to reach persistent servers.

Connect

1. Open Settings → Machines and click Add machine.
2. Select an SSH-config alias or enter the connection details below.
3. Test and save the connection, then connect.
4. Open the machine's System tab and check Workspace Runtime. Install or start it if prompted.
5. Add a remote project.

The remote host needs SSH access, a writable home directory, Git and your development tools. For Emdash 1.2.8, use Linux x64 or ARM64 with glibc. Other hosts require a compatible Workspace Server release.

Configure Manually

Enter a name for the connection and provide Host, Port and Username.

Supported authentication methods are:

• Password stores the password in encrypted app storage.
• SSH Key reads the private key from the path you provide. If you enter a passphrase, Emdash stores it in encrypted app storage.
• Agent uses the SSH agent socket available to the Emdash process. If SSH config resolves an IdentityAgent for the host, Emdash uses that socket. Otherwise it falls back to SSH_AUTH_SOCK.

Advanced options:

• ProxyJump connects through one or more jump hosts.
• ForwardAgent forwards your local SSH agent to the remote host.

Select From SSH Config

If you already connect using ssh <alias>, you can select that alias instead of copying every field into the form.

Emdash reads your local ~/.ssh/config, follows Include directives and shows the concrete Host aliases in the SSH Config selector.

When you select an alias, Emdash saves the alias and runs ssh -G <alias>, then uses the host, port, username, authentication, proxy, forwarding, timeout and keepalive settings OpenSSH resolves for that alias to connect.

Selecting an alias fills the resolved connection details. You can override the authentication method and private key in Emdash. Use Reset to SSH config to clear a key override.

Authentication Resolution

For key authentication, Emdash uses the manual private key path when one is configured. For SSH config aliases, it can use the first resolved IdentityFile.

For agent authentication, Emdash resolves the agent socket from SSH config first. IdentityAgent none disables agent authentication for that alias. If no IdentityAgent is resolved, Emdash uses SSH_AUTH_SOCK.

When IdentitiesOnly is enabled with agent authentication, Emdash only offers matching agent identities. OpenSSH user certificates supplied by the SSH agent are supported.

Proxying And ForwardAgent

Manual connections support ProxyJump and ForwardAgent. SSH config aliases support ProxyJump, ProxyCommand and ForwardAgent. If both ProxyCommand and ProxyJump resolve from SSH config, ProxyCommand takes precedence.

Proxy helpers run on the local machine running Emdash. A ProxyCommand that calls a helper such as cloudflared requires that helper to be installed locally.

ProxyJump uses the local ssh command with -W to reach the final destination. Multiple jump hosts are supported with comma-separated ProxyJump values, such as bastion-a,bastion-b.

ProxyCommand supports the OpenSSH tokens %h, %p, %r, %n, and %%. Unsupported percent tokens are stripped before the command runs.

When ForwardAgent is enabled, Emdash forwards the resolved agent socket. If the forwarded agent and the authentication agent resolve to different sockets, Emdash stops instead of opening an ambiguous connection.

Supported SSH Config Directives

Emdash resolves these SSH config directives:

• Destination: Host, HostName, User, Port
• Authentication: IdentityFile, IdentityAgent, IdentitiesOnly
• Proxying: ProxyJump, ProxyCommand
• Agent forwarding: ForwardAgent
• Timeouts and keepalive: ConnectTimeout, ServerAliveInterval, ServerAliveCountMax

Other SSH config directives may still affect helper commands run by OpenSSH, such as the local ssh command used for ProxyJump, but they are not directly mapped into Emdash's SSH client.

Local Requirements

The machine running Emdash needs:

• Local ssh for SSH config aliases and ProxyJump.
• Local helper commands required by your ProxyCommand.
• A local SSH agent socket for agent authentication or ForwardAgent.

The remote host still needs an SSH server and whatever credentials, Git setup and development tools your remote project requires.

Troubleshooting

• SSH fails: test ssh <alias> locally. Check the username, key or agent, and any proxy helper.
• SSH connects but projects fail: check Workspace Runtime in the machine's System tab. Read the error, then install, start or update the runtime as needed.
• Tailscale SSH: supported from Emdash 1.2.2. The server must support Unix socket forwarding.
• Tools aren't detected: install them on the remote machine and check the remote user's PATH and shell setup.
• Connection drops: let Emdash reconnect or retry from Machines. Check the host and network if recovery fails. For terminal persistence, see tmux.

The runtime connects through an SSH-forwarded Unix socket. Check SSH forwarding policy if authentication succeeds but runtime access fails.