This page describes Calíope 1.5, the version I am building right now. 1.4 is on the App Store for the Mac, iPad, iPhone, Apple Watch, Apple TV and Apple Vision Pro. 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 a database server behind an SSH bastion without exposing its port.
Where it is: Sidebar › Profile form › SSH Tunnel
An SSH tunnel (also called port forwarding) allows Calíope to communicate with a database server that is not directly accessible from your network. Instead of connecting to the server's host directly, Calíope first opens an SSH session with a bastion server, and through that session creates an encrypted channel to the internal 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 database 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 database destination as seen from the bastion, not from your machine. If the database server 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.
On the Mac, Calíope keeps secure access to the file (security-scoped bookmark) so it can read it on later launches without you selecting it again. ⚠️ If you move or rename the key file, Calíope will not be able to read it on the next connection and will show the error "The SSH key file is no longer accessible"; open the profile and select the file from its new location.
On iPad and iPhone, choosing or pasting the key keeps a copy of it in Calíope, on this device: moving the original does not affect it, and it never travels to iCloud, even with sync turned on.
On any other device the profile arrives without the key: the file and its location stay on the device where you chose it. The connection list shows Choose its files on this device and the form says “This profile uses a private key chosen on another device: choose it here.”: choose it there.
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 the database 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 database host from the bastion
4. Launches a local proxy on an ephemeral port on 127.0.0.1
5. Connects to that local port with the engine's driver 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 server version. If it fails, the error message will indicate at which step the problem occurred (SSH authentication, database host unreachable, incorrect database 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
Server unreachable from the bastion
The profile's Host field must be the database host as seen from the bastion. Try 127.0.0.1 if the database server is on the same machine 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 the server rejects the connection
Database credentials (username/password) are independent of SSH credentials. Verify that the database 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.
Screens that cannot ask
- The monitor, the topology, scheduled reports and reconnecting have no dialog in which you could decide. If the server is not yet among the ones you trust, they stop with “Unknown SSH server” — not with “the fingerprint has changed”, which is kept for a fingerprint different from the saved one.
- To fix it, open the connection once from a screen that asks — Test connection, in the profile form — and trust the fingerprint after checking it.
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.