Backup & restore¶

KorTTY creates encrypted backups of all your settings, connections, credentials, and SSH keys. Use backup and restore to protect your configuration or move it between machines.

Features¶

• Encrypted backups — All backups are encrypted using either password-protected ZIP or GPG encryption
• Configuration backup — Includes connections, credentials, credential environments, SSH/GPG keys, trusted interactive SSH host keys, global settings, custom terminal themes, JobScheduler configuration, snippets and their stored code analyses, AI chat history, AI Swarm chats, local-model registrations (GGUF and MLX), and knowledge-store source metadata
• Regenerable local AI data excluded — GGUF weights, native llama.cpp runtimes, signed-catalog cache, temporary sidecar files, and HNSW snapshots are intentionally not copied into the archive
• Projects directory — All saved project workspaces are included in the backup
• Automatic rotation — Old backups are automatically moved to an old-backups subdirectory with timestamps
• Configurable retention — Set a maximum number of backups to keep (0 = unlimited; oldest backups are deleted automatically)
• Import/restore — Restore from previously created backups with optional overwrite control
• Flexible decryption — Both password-encrypted ZIP and GPG-encrypted formats are supported for import; korTTY recognises the format from the file content, not from its name

Creating a backup¶

1. Open Edit → Create Backup... or press Ctrl+Shift+B (Cmd+Shift+B on macOS)
2. Select a destination directory for the backup file
3. The backup is created using the encryption method configured in Settings → Backup

KorTTY names the current backup kortty-backup.zip (password-protected ZIP) or kortty-backup.zip.gpg (GPG) in the target directory. The new backup is written completely first; only then is any current backup of either kind already there rotated into an old-backups subdirectory with a timestamp appended, keeping its .zip or .zip.gpg ending (e.g., kortty-backup_2025-06-24_14-30-45.zip.gpg). If creating the backup fails, the existing current backup stays untouched.

The backup includes:

Automatic backup¶

Instead of remembering to run Create Backup, let korTTY do it: in Configuration → Global Settings → Backup → Automatic backup choose a schedule (daily, weekly or monthly) and an existing folder, for example on a network drive. korTTY then writes the same encrypted backup there on its own, checks two minutes after each start and then hourly whether one is due, and catches up on a backup missed while it was closed. The settings page describes the status line and the conditions under which a run is skipped: Automatic backup.

Backup encryption¶

Password-protected ZIP (default)¶

1. Open Settings → Backup
2. Select ZIP with Password under Backup Encryption
3. Choose or create a credential to use as the encryption password
4. Optionally set Maximum number of backups (0 = unlimited)
5. Save

Password-protected backups are encrypted with AES-256 (via the zip4j library); the credential's password encrypts all files in the archive. Backups created by older korTTY versions used legacy ZIP encryption and can still be imported — the decryption method is read from the archive itself. Note that AES-encrypted ZIPs need an AES-capable tool (7-Zip, WinZip, unzip 6+) if you ever extract one outside korTTY.

GPG encryption¶

1. Open Settings → Backup
2. Select GPG Encryption under Backup Encryption
3. Choose the key in the GPG Key field; keys are managed under Configuration → Security → GPG-Keys...
4. Optionally set Maximum number of backups (0 = unlimited)
5. Save

GPG backups are encrypted for the public key of your selected GPG key. KorTTY builds an unencrypted ZIP in a private temporary folder that only your user can read, encrypts it with gpg, stores the result as kortty-backup.zip.gpg and then deletes the temporary ZIP with its folder. Creating a GPG backup needs the installed gpg and the recipient's public key; restoring it needs gpg and the matching private key, so keep that key (and its passphrase) somewhere other than the backup.

Importing a backup¶

1. Open Edit → Import Backup...
2. Select a backup file (.zip or .zip.gpg)
3. If the backup is a password-protected ZIP, enter the password when prompted; GPG backups ask for no ZIP password — gpg may ask for the passphrase of your private key instead
4. Choose whether to Overwrite Existing Files:
5. OK — Backup files will replace any existing files in your configuration
6. Cancel — Existing files are skipped; only missing files are imported
7. Restart the application for all changes to take effect

KorTTY recognises the backup format from the file content, not from its name, so GPG backups that older versions saved as kortty-backup.zip import as GPG backups too. A file that is neither a ZIP archive nor GPG-encrypted is rejected before anything is restored.

After the import, korTTY reloads the restored connections, credentials, environments, SSH and GPG keys, settings, themes, snippets, snippet variables and saved AI and swarm chats, so a later save does not overwrite them with what was loaded before. The open terminal tabs then show the tab colors of the restored connections and credential environments.

Each restored file replaces the local one atomically, so an interrupted import never leaves a half-written file behind. On macOS and Linux, connections.xml, credentials.xml, ssh-keys.xml, job-scheduler.xml and master.key are restored owner-only (rw-------); the other files keep the permissions of the file they replace, and a file that did not exist locally is created owner-only. If a restored connections, credentials, SSH key, GPG key or environments file cannot be parsed, the reload moves it aside as <name>.corrupt-<timestamp> and korTTY keeps what it had loaded before, which its next save writes to a fresh file; a themes file that cannot be parsed is moved aside the same way and replaced by the built-in themes.

Backup file contents¶

Both .zip and .zip.gpg backups contain the same files:

• connections.xml — All SSH connections and groups
• credentials.xml — Stored credentials (still encrypted with your master password)
• environments.xml — Custom credential environments and environment tab colors
• ssh-keys.xml — SSH key references and encrypted passphrases
• ssh-keys/ — Copied SSH key files (only keys you placed there via Copy to User Directory; keys referenced in their original locations are not collected). Restored key files get owner-only permissions, and an import merges — it never deletes or, without Overwrite, replaces keys already present
• ssh-host-keys.properties — Trusted public host keys for interactive Terminal, SFTP, and Mosh bootstrap connections (ssh-host-keys.properties.lock is intentionally excluded)
• gpg-keys.xml — GPG public keys
• global-settings.xml — Application settings, AI profiles, terminal defaults
• themes.xml — Terminal color themes, including your own
• job-scheduler.xml — JobScheduler jobs, host-key pins, encrypted sudo passwords
• snippets.xml — Code snippets and templates
• snippet-variables.xml — Custom snippet variables
• snippet-analyses/ — Stored Full code analyses, one file per snippet. An import merges them: analyses that exist only locally are kept, missing ones are added, and with Overwrite a local file is replaced only when the backup's copy is newer. Unsaved snippet drafts (snippet-drafts/) are not included
• ai-chats.xml — Saved AI conversations
• swarm-chats.xml — Saved AI Swarm chats
• memory/ — The AI memory: MEMORY.md, the notes of each connection, the history, the archive and the state (see AI memory). A restore adds only the files that do not exist locally and never overwrites one. A note that holds a possible secret is not restored, and nothing is restored when the enterprise policy makes the memory read-only or disabled. The approvals of other tools' reference files (external.json) are in the archive but are never restored, so you approve them again on the new computer
• stats/ — The AI skill statistics (skill-usage.json); restored only where no local statistics file exists
• master.key — Salt and verification hash of your master password, so the restored secrets can be unlocked with it
• llm/models.xml — Local GGUF registrations and runtime settings (model weights are not included)
• llm/mlx-models.json — MLX model registrations (model weights are not included)
• rag/stores.json — Knowledge-store and source configuration (vector snapshots are not included)
• projects/ — All saved project workspace files (.kortty)

The session snapshots in ~/.kortty/session/, which File → Restore Previous Session opens, are not included: they describe the windows and tabs of this computer, and the Recently Closed list they keep stays on this computer with them. After a restore, Restore Previous Session still opens the session of this computer, and its tabs open with the restored connections. See Previous session.

Some files stay on the computer as well: master.autounlock, the auto-login file, is deliberately never copied, because its obfuscation key ships with korTTY; the approvals of SSH tunnels (ssh-tunnel-approvals.properties) are not copied either, so after a restore the tunnels of a connection ask again; and the language files generated under Languages in ~/.kortty/i18n/ are not part of a backup.

Backup retention and cleanup¶

When you create a new backup in a directory that already contains one, KorTTY:

1. Creates the new backup — kortty-backup.zip for a password-protected ZIP, kortty-backup.zip.gpg for GPG — and stops here, leaving the existing backup untouched, if that fails
2. Moves every existing current backup, of either kind, to old-backups/kortty-backup_<timestamp>.zip or old-backups/kortty-backup_<timestamp>.zip.gpg; a backup rotated in the same second gets -1, -2 … appended instead of replacing the earlier one
3. If the number of old backups exceeds Maximum number of backups, deletes the oldest ones

Maximum number of backups counts ZIP and GPG backups together. After you switch the encryption type, the first new backup also rotates the current backup of the other type, so the oldest old backup can be deleted one backup earlier than you might expect.

To keep unlimited old backups, set Maximum number of backups to 0 in Settings → Backup. To keep only one old backup next to the current one, set Maximum number of backups to 1.

Using backups across machines¶

1. Export your current configuration:

2. On machine A, open Edit → Create Backup... and save to a USB drive or cloud storage

3. Move the backup file:

4. Copy kortty-backup.zip (or kortty-backup.zip.gpg) to machine B; for a GPG backup, machine B also needs gpg and the private key of the backup's GPG key

5. Import on the new machine:

6. On machine B, open Edit → Import Backup...
7. Select the backup file from step 2
8. Enter the backup password if prompted
9. Choose Cancel in the overwrite question unless you want to replace existing connections
10. Restart KorTTY

All backed-up connections, settings, snippets, saved chats, interactive host-key trust decisions, model registrations, and knowledge-source definitions will be available on machine B. Restored host keys are still matched by normalized host name and port, so a changed key remains blocked after migration. Local model weights, runtime packages, source documents, and HNSW vectors must be restored or regenerated separately.

Troubleshooting¶

"Backup file not found"

Verify the file path is correct and the file exists. Check the directory permissions.

"Password required for password-encrypted backup"

Password-protected backups need the correct password. Verify you are entering the credential password (from Settings → Backup), not your master password.

"… is not a korTTY backup: it is neither a ZIP archive nor a GPG-encrypted file"

The selected file is neither a ZIP archive nor GPG-encrypted data, for example a different file with a .zip name or a backup that was cut off while copying. Select the kortty-backup.zip or kortty-backup.zip.gpg file itself.

"GPG encryption failed"

gpg could not encrypt the new backup: it is not installed, or the selected key's public key is neither in your GPG keyring nor available as the key file stored with the key in Manage GPG Keys.... The previous backup in the target directory is left as it was.

"GPG decryption failed"

gpg could not decrypt the backup: the private key that matches the backup's GPG key is not in your keyring, gpg is not installed, or you cancelled the passphrase prompt. Import the private key into your GPG keyring (for example with gpg --import) and try again.

"GPG key not found"

The GPG key used for encryption is missing. Use Configuration → Security → GPG-Keys... to import or add the key, then try again.

"No password selected for backup encryption" or "No GPG key selected"

Configure a password credential or GPG key in Settings → Backup before creating a backup.

A *.corrupt-<timestamp> file appeared in ~/.kortty

korTTY could not parse that data file at startup or after an import, so it moved the original aside under this name without changing it and continued without its content. Repair the file and, with korTTY closed, move it back under its original name, or restore the file from a backup.

Import succeeded but changes did not take effect

Restart KorTTY for imported settings to become active. If you imported credentials, you may also need to unlock the master password after restart.

Backup file is larger than expected

Large backups can occur if you have many saved AI chats or a large projects directory. GGUF weights, llama.cpp runtime packages, and HNSW snapshots are excluded and cannot be the cause.