Getting started with easySSH

easySSH is a native interface for the OpenSSH tools already included with macOS. Your SSH configuration remains in ~/.ssh/config; connections still use the system ssh and sftp clients. That means hosts configured in easySSH also work in Terminal, scripts and other apps that use OpenSSH.

This guide covers the first setup, safe editing, keys, SFTP transfers and the most common connection problems.

Availability note: The current development build is not yet confirmed for public distribution. Installation instructions and the download link must be added for the final release.

Before you begin

You need:

macOS 14 or later
access details for an SSH server
a user account on that server
either a private key accepted by the server or another authentication method configured in OpenSSH

The server provider or administrator should give you the hostname, username and port. Port 22 is the OpenSSH default, but many hosting providers use a different one.

If you already use SSH on this Mac, easySSH reads your existing ~/.ssh/config. It does not import the file into a separate database. Before the first edit, it is still sensible to know where your own backup is, especially when the file contains complex Include or Match rules.

Never share a private key or passphrase with Corebird support. A private key normally has no .pub suffix. The corresponding .pub file is the public part intended for installation on a server.

Understand the main fields

An SSH host entry can look like this:

Host my-project
    HostName server.example.com
    User project-user
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

The fields have different jobs:

easySSH field	SSH directive	Meaning
Alias	`Host`	The short name you type after `ssh`, such as `my-project`
Server	`HostName`	The real DNS name or IP address of the server
User	`User`	Your account name on the remote server
Port	`Port`	The SSH service port; usually 22 unless your provider says otherwise
Key	`IdentityFile`	The private key on this Mac used for authentication
Jump host	`ProxyJump`	An intermediate SSH host, if your setup requires one

The alias is local. It does not need to match the server name. Once saved, both easySSH and Terminal can connect with ssh my-project.

Add your first host

Open the easySSH manager from its menu bar icon.
In the Hosts section, choose the plus button or New Host.
Replace the temporary alias with a short, memorable name. Avoid spaces if you want to type it easily in Terminal.
Enter the server hostname and username supplied by the server administrator.
Change the port only when your provider uses a port other than 22.
Select the private key that belongs to this account, if key authentication is used.
Add a jump host or further OpenSSH options only when the server setup requires them.
Press Command-S to save.

easySSH does not silently write every field change. Until you save, Connect and Test remain unavailable because the on-disk OpenSSH configuration still contains the previous values.

Before replacing an existing config, easySSH stores a copy in ~/.ssh/config-backups/. The latest 20 copies are retained. The saved config and backups receive owner-only file permissions.

Existing and advanced configuration

easySSH preserves comments, indentation, unknown options and lines it did not edit. Directives without a dedicated field remain in the advanced text area. Match blocks are shown as content that stays unchanged and are not editable in the app.

If the config uses Include, easySSH preserves the Include line but does not display the hosts from the included files. Edit those hosts in their source file.

Open the first connection

Choose the saved host and select Connect. easySSH opens the terminal app selected in its settings and starts ssh with the host alias.

The first time, macOS may ask whether easySSH may control Terminal or iTerm2. This permission is used only to open a window and enter the SSH command. If you declined it:

Open System Settings.
Go to Privacy & Security, then Automation.
Allow easySSH to control the terminal app you selected.
Return to easySSH and choose Connect again.

Confirm a new host key carefully

On the first connection, OpenSSH may show a host-key fingerprint. Compare it with the value published by your hosting provider or supplied by the server administrator before accepting it. The accepted key is stored by OpenSSH in known_hosts.

If OpenSSH says that a host key has changed, do not bypass the warning. A server may have been rebuilt, but the message can also mean that the destination is not the server you expected. Verify the new fingerprint through a separate trusted channel.

Test a saved host

The Test action uses non-interactive SSH and translates common failures into shorter messages. A successful result confirms that the saved alias can sign in without a prompt.

The test is intentionally stricter than an interactive connection. If a key has a passphrase and is not available through ssh-agent, Connect can still work because the terminal lets you enter the passphrase, while Test can report that authentication was refused.

Common results:

Message	What to check
Host name not resolvable	Spelling of Server, DNS availability, or whether an IP address is required
Timed out or server unreachable	Network connection, hostname, port, VPN and server availability
Connection refused	Whether an SSH service listens on the configured port
Sign-in refused	Username, installed public key, chosen private key and SSH-agent state
Key file not found	The path selected under Key
Host key not confirmed	Make one verified interactive connection first

If the same alias also fails in Terminal, the issue is likely in the OpenSSH configuration, network or server rather than the easySSH interface.

Create and use an SSH key

Open the Keys section to see keys found in ~/.ssh. easySSH shows details such as type, length, comment, fingerprint and whether the key appears to be protected by a passphrase.

To create a key:

Choose the plus button in the Keys section.
Enter a file name. easySSH creates that name and a matching .pub file in ~/.ssh and never overwrites an existing file.
Add a comment that helps you recognise the key later.
Enter and repeat a strong passphrase.
Choose Create.

The current version creates Ed25519 keys. The private file stays on your Mac. Use Copy to Clipboard in the Public key section to obtain the text that belongs on the server, commonly in ~/.ssh/authorized_keys or in the provider's control panel.

Do not delete an old private key until every host that uses it has been changed and tested. easySSH warns when a key is still referenced by a visible host entry and moves deleted key files to the Trash, but a key may also be used by scripts or included config files that the app cannot see.

Transfer files with SFTP

The Files section uses the system sftp client and your saved SSH configuration.

Choose a server from the menu and select Connect.
Navigate through the remote folders with the file list and path bar.
Drag a local file or folder from Finder into the remote view to upload it.
Drag a remote item to Finder to download it.

Switch to the two-pane view when you want a local folder and remote folder visible together. You can also create folders, rename entries and change permissions.

Deleting a remote item is permanent. A remote folder deletion also removes its contents. Confirm the server, current path and selected names before continuing. Permission changes, especially recursive ones, can stop a website or service from working even when no file is deleted.

Settings worth checking

Terminal app

Choose Terminal or iTerm2 for interactive connections. Only installed choices are shown.

Start at login

easySSH can register itself as a macOS login item and start with only the menu bar icon visible. macOS may require confirmation under System Settings, General, Login Items.

Language

The interface follows the system language by default. English, German and Spanish can also be selected directly, without restarting the app.

SSH folder permissions

The .ssh folder normally contains private keys and should not be readable by other local accounts. easySSH warns when its permissions are broader than 700 and can set them to 700. If the Mac is managed by an organisation or uses an unusual shared setup, ask the system administrator before changing permissions.

If a save is blocked

When another program changes ~/.ssh/config after easySSH has loaded it, easySSH refuses to save. This protects the newer file from being overwritten.

Save or copy the changes from the other editor.
In easySSH, choose Reload. Unsaved changes in easySSH will be discarded.
Reapply the intended change and save again.

Do not repeatedly force changes through different editors. There is no automatic merge.

If the config becomes unreadable, stop editing and inspect the copies in ~/.ssh/config-backups/. Restore only after comparing the files and understanding which version contains the needed hosts.

Ask for help safely

When opening a support ticket, include:

easySSH and macOS versions
Mac architecture, if known
affected area and terminal app
exact error message
whether the same alias works in Terminal

Replace real hostnames, IP addresses, usernames, fingerprints and paths in anything you paste. Never attach a private key, password or passphrase. Corebird support will not ask for your private key.

[Open a support ticket] [easySSH privacy policy]