This page describes Calíope 1.5, the version we are building right now. 1.4 is finished and in App Review, and the store serves 1.3 on the Mac and 1.2 on iPad. The changelog says which version each feature landed in.
Adds an “Open in Calíope” button to every topic. It only works with the app installed.
Connect to MySQL behind an SSH bastion without exposing port 3306.
Where it is: Sidebar › Profile form › SSH Tunnel
An SSH tunnel (also called port forwarding) allows Calíope to communicate with a MySQL server that is not directly accessible from your network. Instead of connecting to the MySQL host directly, Calíope first opens an SSH session with a bastion server, and through that session creates an encrypted channel to the internal MySQL server.
Typical use case: your database is on a private AWS, GCP, or DigitalOcean network at 10.0.1.5:3306, but only the bastion server at bastion.company.com:22 is accessible from the internet. Calíope opens the tunnel automatically when connecting and closes it when disconnecting.
The MySQL connection works exactly like one without a tunnel; the tunnel is completely transparent to all other tools.
Enable the tunnel in the connection profile and enter the bastion details.
Where it is: Sidebar › Profile form › SSH Tunnel
In the Connection Manager, select the profile and enable the SSH Tunnel toggle in the Server Options section. The configuration section will appear with the following fields:
- SSH Host — hostname or IP of the bastion server (e.g., bastion.company.com)
- SSH Port — typically 22
- SSH User — the user with which you authenticate on the bastion (e.g., ubuntu, ec2-user)
- Authentication — choose between Password or Private key
The Host / IP and Port fields in the main profile remain the MySQL destination as seen from the bastion, not from your machine. If MySQL is on the same machine as the bastion, use 127.0.0.1.
Tap Test connection to validate the full tunnel before connecting.
Use a bastion username and password to authenticate the tunnel.
Where it is: Sidebar › Profile form › SSH Tunnel › Authentication
Select Password in the authentication selector within the SSH Tunnel section. The SSH Password field will appear where you enter the user's password on the bastion server.
The password is saved in the macOS system Keychain, never in the profiles file. It is stored with the internal key ssh-pass-<profile-id> and is only accessible to Calíope.
This method is the simplest, but keep in mind that many modern servers disable password authentication in favor of cryptographic keys.
Use an ED25519 or ECDSA key, with or without a passphrase, to authenticate the tunnel.
Where it is: Sidebar › Profile form › SSH Tunnel › Private key
Select Private key in the authentication selector. A Select button will appear to choose the key file. Calíope stores secure access to the file (security-scoped bookmark) so it can read it on later launches without needing to select it again.
⚠️ If you move or rename the key file, Calíope will not be able to access it on the next connection and will show the error "The SSH key file is no longer accessible". In that case, open the profile and select the file from its new location.
Supported key formats and types:
- ED25519 (ssh-keygen -t ed25519) — recommended, secure and fast
- ECDSA P-256/P-384/P-521 (ssh-keygen -t ecdsa -b 256/384/521)
Keys must be in native OpenSSH format (header -----BEGIN OPENSSH PRIVATE KEY-----). This is the default format of ssh-keygen since OpenSSH 7.8.
Passphrase-protected keys work. Type the passphrase in the profile and Calíope decrypts the key itself (bcrypt-pbkdf + AES-256), on the Mac, the iPad and the iPhone alike; the decrypted key never touches the disk. If the passphrase is wrong, it says so — it does not look like an unreadable file.
⚠️ RSA keys are not supported (limitation of the underlying SSH library). If your bastion only accepts RSA, use password authentication or generate a new ED25519 key and add its public key to the bastion.
Generate a new ED25519 key:
ssh-keygen -t ed25519 -C "caliope@my-mac"
Copy the public key (~/.ssh/id_ed25519.pub) to the bastion: ~/.ssh/authorized_keys.
The Test connection button validates the SSH tunnel and MySQL authentication end-to-end.
Where it is: Connection Manager › Test connection
When you tap Test connection with a profile that has the SSH tunnel enabled, Calíope executes the complete sequence:
1. Opens a TCP connection to the SSH bastion (SSH host : SSH port)
2. Negotiates the SSH protocol and authenticates with the configured credentials
3. Opens a direct-tcpip channel to the MySQL host from the bastion
4. Launches a local proxy on an ephemeral port on 127.0.0.1
5. Connects MySQLKit to that local port and executes SELECT 1
6. Closes the tunnel when the test is complete
If the test succeeds, you will see the green banner with the MySQL server version. If it fails, the error message will indicate at which step the problem occurred (SSH authentication, MySQL host unreachable, incorrect MySQL credentials, etc.).
Keywords: test ssh, test tunnel, verify tunnel, test ssh connection, green banner
Calíope verifies the SSH server's fingerprint to protect you from MITM attacks.
Where it is: Connection Manager › SSH key alert
When Calíope connects to an SSH server for the first time, it displays the SHA256 fingerprint of its public key and requests confirmation before continuing. This behavior is equivalent to StrictHostKeyChecking=yes in OpenSSH.
First connection:
Calíope shows the fingerprint and asks you to confirm it matches the expected server. Tap Trust and connect to accept it. The fingerprint is saved in your device's Keychain.
Subsequent connections:
If the server's fingerprint matches the saved one, the connection proceeds without interruption.
If the key has changed:
Calíope displays a red warning: the server's key has changed. This may indicate:
- The administrator regenerated the key (common after reinstallations or migrations).
- A potential man-in-the-middle (MITM) attack on untrusted networks.
Confirm with the administrator before tapping Update and connect.
Clear a saved key:
To force re-verification, delete the fingerprint from the Keychain using the Keychain Access app by searching for caliope.ssh.hostkey.
Keywords: ssh, host key, fingerprint, mitm, verification, server key, known hosts, ssh security, sha256
"Connection refused" when connecting to the bastion
Verify that the SSH host and port (default 22) are correct and that the bastion's firewall allows incoming connections on that port.
"Authentication failed" or no response from the bastion
For password: check the SSH username and password. For private key: make sure the corresponding public key is in ~/.ssh/authorized_keys on the bastion and that the server allows public key authentication (PubkeyAuthentication yes in /etc/ssh/sshd_config).
"The SSH private key passphrase is incorrect"
The key was read and the passphrase did not decrypt it. Check the Passphrase field of the profile; it is not the SSH user password nor the database password.
"Unsupported SSH key type: ssh-rsa"
RSA keys are not compatible. Generate an ED25519 key and add its public key to the bastion.
"The SSH key file has an invalid format"
The key must be in native OpenSSH format. Convert it with: ssh-keygen -p -m OpenSSH -f your_key
MySQL unreachable from the bastion
The profile's Host field must be the MySQL host as seen from the bastion. Try 127.0.0.1 if MySQL is on the same server as the bastion, or use the private IP (e.g., 10.0.1.5) if it is on another machine in the same network.
The tunnel works but MySQL rejects the connection
MySQL credentials (username/password) are independent of SSH credentials. Verify that the MySQL user has permission to connect from 127.0.0.1 or from the bastion's IP.
Keywords: ssh error, troubleshooting, connection refused, authentication failed, invalid format, rsa not supported, passphrase
How Calíope authenticates the identity of an SSH server and what to do when the new/changed fingerprint dialog appears.
The first time you connect to an SSH server, Calíope does not yet know its public key. Before completing the tunnel, the app shows you the SHA-256 fingerprint of the key so you can verify it and decide whether to trust it.
The dialog appears in any action that opens the tunnel, not only when connecting: testing a connection or loading a profile's databases asks the same way, and accepting there saves the fingerprint just the same.
Fingerprint format
- Calíope computes the fingerprint exactly like ssh-keygen -l -E sha256, using the format SHA256:<base64-no-padding>.
- You can obtain the same fingerprint on the server with: ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub -E sha256.
"Unknown server" dialog (new fingerprint)
- Orange shield-slash icon.
- Shows host:port and the received fingerprint.
- Trust & Connect — saves the fingerprint to the system Keychain under the identifier caliope.ssh.hostkey.<host>:<port> and proceeds with the tunnel.
- Cancel — aborts the connection without saving anything.
"Server fingerprint has changed" dialog (red alert)
- Red shield-exclamation icon.
- Appears when the received fingerprint does NOT match the one you previously saved. It may indicate:
- The administrator rotated the server key (legitimate case).
- A different server is answering on the same IP/port (possible MITM attack).
- Shows both fingerprints: the known one and the new one, side by side.
- Update & Connect — overwrites the stored fingerprint and connects. Use it only after confirming the rotation via an out-of-band channel.
- Cancel — keeps the previous fingerprint and aborts.
Resetting the known fingerprint
- There is currently no UI to delete an individual fingerprint, but you can force re-verification by removing the entry from Keychain (Keychain Access › account caliope.ssh.hostkey.host:port) and reconnecting.
- Reinstalling Calíope wipes all fingerprints and you'll see the "Unknown server" dialog on the next connection.
Best practices
- Compare the fingerprint against what the server administrator sent through a secure channel (signed message, HTTPS site, etc.).
- If the red dialog appears without an obvious reason, cancel and verify with the administrator before accepting.