Configuration files¶

KorTTY stores all application data and configuration under the ~/.kortty/ directory in your home folder. This guide documents every file and subdirectory, their purpose, and how they are used.

Directory structure¶

~/.kortty/
├── connections.xml                    # Saved SSH connections
├── credentials.xml                    # Stored credentials (encrypted)
├── environments.xml                   # Your own credential environments and environment tab colors
├── ssh-keys.xml                       # SSH key management
├── gpg-keys.xml                       # GPG keys for backup encryption
├── global-settings.xml                # Global application settings
├── llm/
│   ├── models.xml                     # Local GGUF registrations/settings
│   ├── models/                        # Managed GGUF weights
│   ├── runtime/                       # Versioned llama.cpp packages, activation and revocation state
│   ├── catalog/                       # Verified model/prompt catalog cache
│   ├── mlx/                           # MLX runtime, models and temporary run state
│   ├── mlx-models.json                # MLX model registrations
│   ├── huggingface-token.enc          # Optional Hugging Face token, encrypted with the master password
│   └── run/                           # Temporary sidecar state
├── rag/
│   ├── stores.json                    # Knowledge stores and source configuration
│   └── stores/                        # Local HNSW snapshots
├── ai-chats.xml                       # Saved AI conversations
├── memory/                            # AI memory: MEMORY.md, connection notes, history and state (owner-only; see below)
├── stats/                             # AI skill usage statistics (owner-only; see below)
├── snippets.xml                       # Code snippets and scripts
├── snippet-variables.xml              # Snippet variable storage
├── snippet-analyses/                  # Stored Full code analyses, one <snippet-id>.json per snippet
├── snippet-drafts/                    # Unsaved snippet-editor forms (owner-only; not backed up)
├── job-scheduler.xml                  # JobScheduler jobs, host-key pins, sudo secrets, journal
├── ssh-host-keys.properties           # Interactive Terminal/SFTP/Mosh host-key pins
├── ssh-host-keys.properties.lock      # Transient cross-process writer lock (not backed up)
├── ssh-tunnel-approvals.properties    # SSH tunnel sets you allowed to open, per connection (not backed up)
├── master.key                         # Hashed master password (PBKDF2)
├── master.autounlock                  # Optional auto-login password (owner-only; not encrypted with the master password)
├── themes.xml                         # Your terminal themes (color profiles)
├── swarm-chats.xml                    # Saved AI Swarm conversations
├── journal-search-visited.xml         # Journal search hits you have already opened
├── sftp-resume-index.json             # Unfinished SFTP transfers that a retry can continue (not backed up)
├── jvm-launch.properties              # JVM resource profile (Settings → Resources)
├── teamwork-cache.xml                 # Cached connections of teamwork sources
├── teamwork-recycle-bin.xml           # Teamwork connections you deleted locally
├── teamwork-repos/                    # Local clones of Git-based teamwork sources
├── telemetry-spool.json               # Anonymous usage events waiting to be sent (see Anonymous data)
├── telemetry-run.marker               # Present while korTTY runs; a leftover marker marks an unclean exit
├── terminal-effect-plugins.disabled   # Disabled terminal-effect plugin IDs
├── coding-agents/                     # User overrides for coding-agent detection rules
├── control/                           # Control API endpoint (owner-only 0700; only while enabled)
│   ├── control.sock                   # Unix socket (Linux/macOS); absent on Windows
│   └── endpoint.json                  # Transport, port and access token (0600); deleted on exit
├── logs/                              # Application log (kortty.log) and its archives; ai-answers/ keeps unusable AI answers
├── history/                           # Terminal session history (compressed)
├── journals/                          # Session journals (one directory per journal)
├── terminal-logs/                     # Default folder for per-connection terminal logs
├── recordings/                        # Default folder for terminal recordings (Video Manager)
├── mosh4j/                            # Downloaded mosh4j release and its dependency JARs for built-in Mosh
├── guide/                             # Generated translations of the manual and their translation memory
├── shell-integration/                 # Wrapper folders of local shells (left-behind folders are removed after a day)
├── plugins/                           # Imported terminal-effect plugin JARs
├── bundled-plugins/                   # Runtime copies of bundled exportable plugins
├── projects/                          # Project files (.kortty)
├── session/                           # Session snapshots for Restore Previous Session (owner-only; not backed up)
├── i18n/                              # Generated language files (messages_*.properties)
└── ssh-keys/                          # Optional copied SSH keys (included in backups)

Core configuration files¶

connections.xml¶

Contains all saved SSH connections with their settings.

Includes: - Connection name, host, port, username - Authentication method (password, SSH key, temporary SSH key) - Terminal appearance overrides (font, colors, size) - SSH tunnels and jump server configuration - Optional per-connection SSH host-key verification override (verify, don't verify, or inherit) - Optional per-connection character encoding (encoding; missing means the default — see Terminal → Encoding) - Terminal effect plugins and animation speed - Connection-specific terminal logging settings - Per-connection session journal settings (enable, capture typed input, AI summaries, summary interval) - Window geometry preferences - Group/folder organization - Optional free-text tag (used for search, bulk tagging and tag-based export) - Optional OS symbol (osBadge): the id of a built-in symbol such as redhat or windows-11, or custom:<id> for one of your own (see OS symbols) - Connections per day of the last 30 days (usageHistory, yyyy-MM-dd=count entries), shown as the usage bars of the Connection Manager's inspector; never exported - Optional keyword highlighting rule set (highlightRuleSetId): the id of a built-in or your own rule set, none for no highlighting, or missing to follow the default rule set (see Rule set per connection). Connections from a teamwork file can carry it as well; the id of a rule set that does not exist on your computer is ignored. - Optional paste protection that overrides Settings → Terminal → Paste protection for this connection: pasteWarningMode (off, unless-bracketed or always) and pasteLineDelayMs (0 to 1000; 0 pastes at once). Missing means the global setting, and an unknown warning mode counts as missing (see Paste protection). Connections from a teamwork file can carry both, but their warning mode applies only when it asks more often than your own setting. - Optional tab color (tabColor, #RRGGBB) that marks the connection's terminal tabs with a colored dot; anything that is not a hex color is ignored (see Tab color). Connections from a teamwork file can carry it as well, so the file's maintainer decides how those tabs are marked.

Security: Connection passwords are encrypted with AES-256-GCM using the master password.

credentials.xml¶

Centralized credential storage for username/password pairs.

Includes: - Credential name, username, password - Environment (Production, Development, Test, Staging, or one of your own from environments.xml) - Server pattern (glob patterns like *.example.com or 10.0.0.*) - Auto-assignment to connections matching the pattern

Security: All passwords are encrypted with AES-256-GCM.

environments.xml¶

Your own credential environments and the tab colors of all environments (see Environments and tab colors).

Includes: - Custom environments with their id and display name (<environment id="custom-…" displayName="Lab"/>); the built-in Production, Development, Test and Staging are not stored - Optional tab colors of built-in and custom environments (<colors><color id="PRODUCTION" color="#D32F2F"/></colors>); a value that is not a hex color, or the color of an environment that no longer exists, is ignored

A file without colors, as earlier versions wrote it, loads unchanged. Without the file korTTY has only the built-in environments, and no environment has a color.

ssh-keys.xml¶

Manages centralized SSH key storage.

Includes: - SSH key path - Key passphrase (if the key is protected) - Optional description - Key fingerprint

Security: Key passphrases are encrypted with AES-256-GCM using the master password.

ssh-host-keys.properties¶

The versioned trust-on-first-use store for interactive Terminal and SFTP connections and the SSH bootstrap used by Mosh. Entries are keyed by normalized host name and port and contain the public-key algorithm, OpenSSH SHA-256 fingerprint, OpenSSH public-key line, and trust timestamp. A matching key is accepted silently after first-use confirmation; a changed key is hard-blocked and is not replaced automatically. Entries are replaced through Review and Replace… in the changed-key alert and removed under Configuration → Security → Known Hosts…; removing the last entry deletes the file, which counts as an empty store. When host-key verification is relaxed to accept-new for a connection, an unknown key is pinned without the confirmation prompt — a changed key is still refused in both modes.

Writes use a temporary file plus atomic replacement, while ssh-host-keys.properties.lock coordinates separate korTTY processes so their pins are merged safely. The properties file is included in encrypted backups; the transient lock file is not. This endpoint-based store is separate from the JobScheduler host-key pins in job-scheduler.xml, which are keyed by connection ID for unattended operations.

ssh-tunnel-approvals.properties¶

Remembers which SSH tunnels you allowed korTTY to open: one entry per connection ID with a SHA-256 fingerprint of the server, of whether the connection is your own or shared (Teamwork), and of the enabled tunnels. When a connection's tunnels or its server change, the fingerprint no longer matches and korTTY asks again before it opens them. The file is not part of a backup, so a restored or migrated configuration asks once more; deleting it has the same effect.

gpg-keys.xml¶

Stores GPG key information for backup encryption.

Includes: - GPG key ID - Key email address - Optional fingerprint - Import source (system keyring or manual entry)

global-settings.xml¶

Global application preferences and defaults.

Contains: every preference of the Global Settings dialog, grouped below by the area it belongs to.

Appearance and fonts¶

• UI theme and appearance settings
• Font family and default size
• UI font size (percent, 80–160%, or auto-derived from the display resolution) and the manual's separate text size (70–250%)
• Terminal color configuration

Window, menus and panels¶

• Main-window geometry and state (position, size, maximized status), plus a named geometry entry for every user-resizable application dialog
• Menu bar visibility preference
• Dashboard visibility state
• "Open tool windows as tabs" flag
• connectionColorBorderEnabled: whether the terminal of a connection with a tab color gets a frame in that color, and a split pane of a connection with a different color a frame of its own (on by default)
• splitPaneFocusRingEnabled: whether the pane the keyboard is in gets a focus ring while a tab has two or more split panes (on by default)
• connectionGroupColors: the tab colors of Connection Manager folders, one <group path="Work/Production" color="#D32F2F"/> entry per folder with a color of its own; an entry whose color is not a hex color is ignored, and without the element no folder has a color
• customOsBadges: your own OS symbols, one <badge id="…" name="…" file="….png"/> entry each; the images are in the os-badges folder of the configuration directory
• favoriteConnections: the ids of the connections marked as favorites in the Connection Manager, one <connection> entry each; teamwork connections can be favorites too
• tabTitleFromShellEnabled: whether a terminal tab shows the title its shell sets in place of the connection's name (on by default)
• tabSwitchMostRecentFirst: whether Ctrl+Tab switches tabs in the order they were last used instead of their tab bar order (off by default)
• recentProjectPaths: the absolute paths of the project files you opened or saved last, newest first, at most 10, which File → Open Recent lists; openRecentClearedAt: when you last chose Clear List there (milliseconds since 1970, 0 for never)
• sessionRestoreMode: what korTTY does at startup with the previous session: ask offers it in a bar (the default, also for a missing or unknown value), auto restores it once no dialog is open, off does nothing
• sessionRestoreScrollback: whether a restored session also shows the saved output of each terminal pane (off by default); sessionRestoreScrollbackLines: how many lines of output are kept per pane, 100 to 5000 (1000 when missing)
• keyBindingOverrides: your own keyboard shortcuts, one binding entry per changed command, such as menu.view.commandPalette=Shortcut+Alt+P or menu.view.dashboard=none; without it every command keeps its default shortcut
• Docked live session-journal panel: placement (hidden/left/right) and width
• Coding Agents panel: codingAgentPanelPlacement (hidden, left or right), codingAgentPanelSide (the side it was last docked on, kept while it is hidden), codingAgentPanelWidth, and codingAgentPanelAutoVisibility (show and hide it with agent detection, on by default)
• Icon toolbar: the iconToolbar element with the visibility of the action row (visible attribute) and of the connection row (connectionsVisible), and one entry per button with id, kind (ACTION, CONNECTION, GROUP or SEPARATOR), section (TERMINAL, TOOLS, SETTINGS or CONNECTIONS) and target (an action id, a connection id or a group path). Entries hold references only, never passwords or keys; without the element the default layout applies. The logfileManagerMigrated attribute records the one-time addition of the Logfile Manager to older layouts, preserving existing entries and allowing later customization to remove it; the connectionManagerMigrated attribute does the same for the Connection Manager button
• windowsShellsMigrated (an attribute of iconToolbar): records the one-time addition of the PowerShell and Command Prompt buttons on Windows; on other systems it stays false until the layout is loaded on Windows.
• toolbarIconSize: the icon size of both toolbar rows and the customization catalog, 16 to 64 pixels (24 when missing)
• JobScheduler status display preference
• Last ASCII Art dialog preview zoom level
• Last ASCII Art picture size (Small to Extra large) for the AI Picture tab, and separately for the Image File tab
• Last ASCII Art copy format: comment style, output-code style and gap

Terminal and connections¶

• Default terminal encoding for SSH connections, and terminalEncodingConfirmed, which records that a value stored by an older version has been saved again and applies (see Terminal → Encoding)
• Terminal logging defaults
• Terminal effect plugin defaults
• SSH keep-alive settings
• Connection timeout and retry defaults

Keyword highlighting¶

• The master switch (terminalHighlightingEnabled), highlighting in full-screen programs (terminalHighlightAlternateScreen), the default rule set (defaultHighlightRuleSetId, the id of a built-in or your own set; empty means none) and whether rules with an action may notify or run their snippet (terminalTriggersEnabled)
• Your own rule sets (highlightRuleSets), as edited in the rule-set editor: each set has a stable id, a name and its rules in priority order, and each rule its id, whether it is on, the pattern, whether it is a regular expression, ignore case, whole word, whether it colors the match or the whole line, the text and background colors (#RRGGBB, a theme color ansi:0 to ansi:15, or empty to keep the program's color), bold, italic and underline, and its action (NONE, NOTIFY or RUN_SNIPPET), its optional name, whether a notification carries the matched text and the id of the snippet it runs (snippetId; see Notifications for matching output and Running a snippet when output matches). Which connections you allowed a rule's snippet for is not saved: korTTY asks again after a restart
• The built-in rule sets are not stored: they come with korTTY, so a new version can improve them, and their ids start with builtin., which your own sets cannot use

AI, models and knowledge stores¶

• AI profile defaults, Text/Coding role assignments, embedded GGUF references, prompt presets, and knowledge-store associations
• RAG embedding model ID and llama.cpp preferred runtime backend/update policy
• The Hugging Face token is not stored in this file; it is kept encrypted in llm/huggingface-token.enc
• AI request timeout in minutes (0 = no limit)

Session journal¶

• Storage folder and capture-log format
• AI summaries (interval and profile) and the AI screenshot analysis toggle
• Note translation language
• AI line window and token budget
• Journal page appearance and live-log tail height
• Custom markers and marker rules
• The remembered journal window geometries

Snippets and translation¶

• Snippet input-hardening defaults (enabled, options, max file size)
• Snippet translation target language
• Translation API settings

Export and recording¶

• PDF export watermark (off by default; custom text and colour)
• Document export footer (on by default; custom text)
• Video/recording preferences

Security and backup¶

• Master password auto-login flag (skipMasterPasswordPrompt)
• SSH host-key verification opt-out: the global flag and the list of connection groups whose checking is relaxed to accept-new
• Backup encryption method and retention settings

llm/models.xml¶

The atomically written JAXB registry for locally installed or referenced GGUF models.

Contains:

• Stable model ID and display name
• GGUF path and compatible llama-server executable path
• Backend (AUTO, CPU, METAL, or VULKAN)
• Context size, CPU threads, GPU layers, and idle-unload minutes

The registry contains paths and settings, not model weights or API keys. llm/models/ holds managed GGUF copies, llm/runtime/ holds independently updated native packages, and llm/run/ holds temporary process directories, logs, and owner-only generated key files. Temporary keys are removed when the sidecar stops.

llm/runtime/¶

The regenerable native-runtime area contains immutable package directories plus small atomic state files:

• active-v1 points to the currently selected installation.
• pending-first-launch-v1 records a candidate and its rollback base until a real GGUF-backed authenticated API start succeeds.
• healthy-history-v1 retains at most the two newest confirmed, non-revoked installations.
• revoked-v1 is the durable denylist learned from verified signed indexes; a revoked package also contains .kortty-runtime-revoked.
• blocked-active-v1 remembers the runtime ID removed from active use by a withdrawal so the UI can explain why local AI remains blocked.
• pinned-runtime-v1 holds the runtime ID the user switched to with Other version…; while present, update checks keep that version. The MLX runtime area llm/mlx/runtime/ uses a file of the same name.
• packages/ contains extracted verified installations, while downloads/ is temporary staging protected by the updater lock.

Do not edit or delete the denylist/quarantine markers to re-enable a package. Runtime launches independently enforce them, and a compatible signed replacement must be installed instead. The entire directory is excluded from backup because packages and state can be recreated from the signed stable channel.

llm/catalog/last-valid-catalog-v1.json¶

An atomic cache envelope containing the last model/prompt catalog payload and its detached signature. korTTY re-verifies the signature and strict schema before every cache use. If the application has no valid catalog public trust root, this file is ignored and the built-in bootstrap is used without a network refresh. The cache is regenerable and is not included in backups.

rag/stores.json¶

The atomically written, owner-readable JSON registry for knowledge stores and their sources.

Contains:

• Store ID/name/type, local snapshot directory or Qdrant endpoint/collection, embedding model ID and vector dimensions
• Text, Coding, and autonomous-use assignments
• Per-source stable ID, canonical path, file/directory type, enabled flag, automatic/manual sync mode, size limit, include/exclude globs, .gitignore preference, content hashes, last status, file/chunk/problem counts, and last successful index time

The rag/stores/ subdirectory holds regenerable index.hnsw snapshots. A v2 snapshot embeds its format version, vector dimensions, embedding model ID, hierarchical graph parameters, entry point, chunk metadata, vectors, node levels, and per-layer neighbors; a mismatch is rejected and requires a rebuild. A valid legacy single-layer v1 snapshot is rebuilt and atomically migrated when opened.

job-scheduler.xml¶

All JobScheduler jobs and related data.

Contains: - Job name, enabled status, action type (COMMAND, SNIPPET_SCRIPT, AI_AGENT, SFTP, RSYNC_SYNC) - Schedule configuration (weekdays, times, intervals, date ranges) - Target servers or groups - Host-key pins (OpenSSH public-key material for unattended execution) - Sudo passwords for servers and groups (encrypted) - Journal entries with timestamps, exit codes, and redacted output - Journal retention settings (auto-delete entries older than 14 days by default)

Security: - Host-key pinning is required by default for unattended SSH/SFTP/Rsync execution - Sudo passwords are encrypted with the master password - Journal entries are stored with KorTTY-managed secrets redacted before persistence - Archive passwords and backup encryption credentials are stored encrypted

ai-chats.xml¶

Saved AI conversations and chat history.

Includes: - Chat title and creation timestamp - Conversation messages and responses - Associated AI profile used for the chat - Follow-up prompt history (for context)

Note: AI result tabs are not automatically saved. You must explicitly save them from the AI tab using the Save button to add them to this file.

memory/¶

The AI memory of korTTY, see AI memory. MEMORY.md holds the global memory and connections/<id>.md the memory of each connection; both are plain Markdown that you can read and edit. korTTY marks the entries it wrote with an HTML comment that carries a hash, so an entry you edit becomes your own text, and korTTY never changes or deletes your text without your confirmation.

The other files in the folder are state.json (digests and the state of the memory), history/ (the snapshots korTTY takes before a change, which the Memory tab can restore), archive.md (the korTTY entries that a clean-up archived, which Show archive... lists), learning.json (the state of rule learning, such as the daily counts and the snoozed and declined proposals) and external.json (the reference files of other tools that you approved, with their paths and the SHA-256 of the approved text).

All of them are written owner-only. The folder is included in backups. A restore adds only the files that do not exist locally and never overwrites them; a note that holds a possible secret is not restored; nothing is restored when the enterprise policy makes the memory read-only or disabled. external.json is never restored, so you approve the reference files again on each computer.

stats/¶

skill-usage.json holds the usage counts and the size history of your AI skills for the skill statistics. Daily values are kept for 400 days, monthly values for five years and yearly values without a limit. The file is written owner-only and is included in backups; a restore adds it only where no local statistics file exists. Reset... in the statistics dialog deletes what the file holds.

snippets.xml¶

Code snippets, scripts, and templates.

Includes: - Snippet name, description, language - Code content with syntax highlighting metadata - Category/folder organization - Tags and metadata - Target system (Operating System column: Linux, macOS, Windows, etc.) - Import/export history

Features: - Support for JSON/XML/YAML import/export - Plain-text script export - ZIP archives with optional password or GPG encryption - Local syntax highlighting with Monaco editor - AI-assisted editing and code generation - Persisted Mermaid diagrams (logical-structure flowchart, sequence, state, class, ER) with stable code-reference node IDs and, for selection-scoped diagrams, the covered line range - One-liner export with optional script arguments

snippet-variables.xml¶

Stores variable definitions for use within snippets.

Includes: - Variable name, value, type - Scope (local or shared) - Default values and validation rules

master.key¶

Binary file containing the hashed master password.

Format: PBKDF2 hash with 310,000 iterations

Security: This file does not contain the actual master password—only a cryptographic hash used to verify the password you enter on startup. If this file is lost or corrupted, you must restart KorTTY and set a new master password (though you will lose access to previously stored encrypted credentials and SSH key passphrases).

master.autounlock¶

Written only while auto-login is enabled: a copy of the master password, encrypted only with a key built into korTTY (AES-256-GCM), not with the master password itself, with owner-only file permissions. Deleting it (or disabling the option) restores the normal startup prompt.

terminal-effect-plugins.disabled¶

Text file listing disabled terminal-effect plugin IDs (one per line).

Purpose: When you disable a terminal-effect plugin via Plugins > Terminal Effects, its ID is written to this file so it remains disabled after restart.

coding-agents/¶

Optional user overrides for the coding-agent detection rules, one JSON file per agent (claude-code.json, codex.json, gemini-cli.json, minimax-code.json, qwen-code.json, opencode.json, cursor-agent.json, aider.json, amp.json, goose.json, crush.json, kiro.json, continue.json, grok.json, jules.json, copilot.json, grok-build.json, antigravity.json, cline.json, kilo.json).

Purpose: A file here replaces the bundled rule file of the same agent entirely. An invalid file is reported in the log as a coding-agents warning and the bundled rules stay in effect. The directory does not exist until you create it. See Coding agents → Custom rules.

kortty.log¶

Application log file, in the logs/ folder: ~/.kortty/logs/kortty.log by default, or the folder set under Settings → Logging → Log directory.

Contains: - Startup messages - Connection attempts and results - Terminal session events - Configuration changes - Errors and warnings - Performance metrics (on request via JMX)

Rotation: Each day the current file is closed and the log continues in kortty.YYYY-MM-DD.log. Archives older than 24 hours are compressed automatically, and Settings → Logging → Keep logs deletes archives older than the number of days you choose (0 keeps them all). An enterprise policy can cap the number of archives and their total size.

ai-answers/: The logs/ai-answers/ folder keeps the last few AI answers that korTTY could not use, complete, next to the log, so a failed step can be looked into afterwards. The folder is bounded to a handful of answers.

Directories¶

history/¶

Screen snapshots saved with projects.

Format: GZIP-compressed UTF-8 text, one file per terminal tab of a saved project

Naming: {session-id}.history.gz, referenced by file name from the project's .kortty file

Purpose: Holds the last visible screen of each terminal tab's primary pane at the time the project was saved — not the scrollback, and not the screens of further split panes.

Access: Read only when a project is opened with Auto-Reconnect enabled; the text is then shown dimmed, locally, above the new session and is never sent to the server. No history search uses these files. korTTY only reads, writes and deletes plain {session-id}.history.gz names directly inside this folder. The files are not encrypted.

journals/¶

Session journals — one self-contained directory per journal (location configurable in Settings > Logging > Session Journal). Each journal directory holds journal.xml (the curated document: metadata, AI summaries, markers, notes, screenshot references), the append-only capture log session-log.json / .xml / .yaml (JSON Lines by default) with zstd-compressed rotated parts (part size and part count are configurable per connection on the Journal tab, defaults 25 MB and 20 parts; journals from older versions keep their gzip-compressed .gz parts), the generated journal.html timeline page, and screenshots/*.png. See Session journal.

The journals folder may also hold a .semantic-index/ folder for semantic journal search, and each journal directory a derived search-card.json cache. korTTY rebuilds either one when it is missing, and deleting a journal removes its cache with it.

terminal-logs/¶

Default target folder for per-connection terminal logs when a connection's log folder field is left empty. File naming, daily rotation, compression and retention follow the connection's logging configuration.

plugins/¶

User-imported terminal-effect plugin JARs.

Purpose: External terminal-effect plugins that you import via Plugins > Terminal Effects > Import.

Security: Imported plugins are trusted Java code and are not sandboxed. Only import JARs from sources you trust.

Cleanup: If you delete a plugin from this directory, it will no longer be available in KorTTY. Disabled plugins remain in this directory but are listed in terminal-effect-plugins.disabled.

bundled-plugins/¶

Runtime copies of bundled exportable terminal-effect plugin JARs.

Purpose: Backup and working copies of built-in plugins that can be exported to external users.

Contents: The MU/TH/UR 6000 effect plugin and any other exportable bundled plugins.

Auto-management: KorTTY automatically manages this directory. Users should not edit it manually.

projects/¶

Project files for saving and loading connection sets.

Format: KorTTY XML-based project format (.kortty files)

Naming: User-defined project names with .kortty extension (e.g., production.kortty, development.kortty)

Contains: - List of open connections/tabs at project save time - Window state (tabs, sizes, active tab) - Dashboard state - Project metadata and creation timestamp

Purpose: Quickly open a pre-configured set of connections for a specific project or workflow.

Usage: Save a project via File > Save Project, restore via File > Open Project or the project history menu.

session/¶

The session snapshots korTTY writes while it runs, so File > Restore Previous Session can reopen your windows and tabs after a restart or a crash (see Previous session).

Files:

• last-session.xml — the open windows and tabs of the running korTTY, rewritten a couple of seconds after each change and once more when korTTY quits, together with the Recently Closed list
• previous-session.xml — the session before this start, which Restore Previous Session opens; at each start korTTY moves last-session.xml here, but only when that session had at least one tab
• session.lock — held locked by the korTTY that writes the snapshots; a second korTTY started meanwhile reads them but never writes
• scrollback/<id>.enc — only with Settings → Window → Session Restore → Also restore the output of each terminal pane switched on: the newest output of one terminal pane, encrypted with the key of the master password (AES-256-GCM), which the snapshots name by scrollbackRef; written only while the vault is unlocked and only after the pane showed new output, deleted when the option is turned off, when the master password changes, when a backup is restored and when no saved session names it any more (see Restoring the output)

Format: XML. The windows and tabs are written like a project with Auto-Reconnect; the Recently Closed list keeps the id of each closed tab's saved connection, its tab group, name and terminal effect. Each snapshot also notes whether korTTY quit normally, whether that run restored its previous session and whether it kept running for a minute afterwards, which tells the next start that korTTY ended right after a restore (see At startup). While the startup offer waits for an answer, last-session.xml keeps the offered session, so it is offered again if korTTY quits or crashes before you choose.

Contains no screen text, scrollback, command timestamps, passwords or temporary SSH keys in the snapshots themselves. The folder each local shell tab and pane was in (an absolute path, used to start the shell there again, see Local shells start where you left them) and the name of the encrypted file with a pane's output in scrollback/, which project files never carry, may appear here; korTTY accepts a folder only as an absolute path without control characters and a scrollback reference only as a plain name. A file in scrollback/ that does not decrypt with the current master password is deleted.

Security: The directory and its files are owner-only (rwx------ and rw-------) and are replaced atomically. A snapshot that cannot be parsed is moved aside as <name>.corrupt-<timestamp>; one that cannot be read is left in place and not written over until the next start.

Backup: Not included in configuration backups: the snapshots describe the windows of this computer.

i18n/¶

Dynamically generated language translation files.

Format: Java properties files (.properties)

Naming: messages_{language-code}.properties (e.g., messages_de.properties for German, messages_fr.properties for French)

Purpose: Stores translations generated by translation APIs (Google Translate, DeepL, LibreTranslate, Microsoft Translator, or Yandex) when you choose to generate language files via Settings > Translation.

Auto-refresh: When you upgrade KorTTY to a new version, generated language files are marked as outdated. Use Settings > Translation > Regenerate outdated to refresh them with any new or changed UI keys.

ssh-keys/¶

Optional directory for copied SSH keys.

Purpose: Stores copies of SSH keys in one place for backup and migration.

How to use: 1. Open Management > Manage SSH Keys... 2. Select an SSH key and click Copy to User Directory 3. The key is copied to ~/.kortty/ssh-keys/

Backup: The key files in this directory are included when you create a backup via Edit > Create Backup (the archive is AES-256- or GPG-encrypted). On import they are restored with owner-only file permissions, and the import merges: local keys are never deleted, and existing files are only replaced with Overwrite enabled.

Benefits: - Centralized location for all SSH keys - Included in encrypted backups - Easy migration to new machines

Security summary¶

File locations by platform¶

All files are stored in the same ~/.kortty/ directory across platforms:

• macOS: /Users/{username}/.kortty/
• Windows: C:\Users\{username}\.kortty\ (or %USERPROFILE%\.kortty\)
• Linux: /home/{username}/.kortty/ (or $HOME/.kortty/)

Backup and recovery¶

When you create a backup via Edit > Create Backup, the following configuration is included:

• All .xml configuration files (connections, credentials, credential environments, SSH key references and passphrases, GPG keys, global settings, JobScheduler, snippets, snippet variables, AI chats)
• master.key
• projects/ directory
• ssh-keys/ directory — copied SSH key files (restored with owner-only permissions; imports merge and never delete local keys)
• ssh-host-keys.properties interactive host-key trust store (not its transient .lock file)
• llm/models.xml local-model registrations
• rag/stores.json knowledge-store/source metadata
• memory/ the AI memory files (see memory/); a restore never overwrites a local file, and external.json is never restored
• stats/ the AI skill statistics (see stats/); restored only where no local file exists

Managed GGUF weights, native runtime packages, temporary sidecar data, original source documents, and HNSW snapshots are excluded because they are large or regenerable. The history/ and i18n/ directories are also not part of a backup, and neither is the auto-login file master.autounlock.

The backup is encrypted (password-protected ZIP or GPG) and saved to a location you specify.

Accessing configuration files¶

You can edit KorTTY configuration directly by:

1. Closing KorTTY completely
2. Opening ~/.kortty/ in your file manager or terminal
3. Editing the XML or JSON file with a text editor
4. Restarting KorTTY to load the changes

Troubleshooting¶

Configuration file not found: - KorTTY creates the ~/.kortty/ directory and all necessary subdirectories on first launch. - If a configuration file is missing, KorTTY uses sensible defaults and creates the file on next save.

Encryption errors: - If you forget your master password, you must delete master.key and set a new password. Previously encrypted data will be inaccessible.

Corrupted XML files: - If a .xml file becomes corrupted, restore from a backup or delete the file. KorTTY will recreate it with defaults on next save.

Knowledge-store registry or snapshot cannot be read: - Restore rag/stores.json from a backup or recreate the store in the AI Manager. Delete only the affected regenerable index.hnsw, then choose Update now to rebuild it from the configured source files.

Interactive SSH host key changed: - Do not reconnect until you have verified the new OpenSSH SHA-256 fingerprint with the server administrator and ruled out DNS, routing, or man-in-the-middle problems. KorTTY deliberately blocks the mismatch without retrying or replacing the stored pin.

Plugin loading issues: - Check kortty.log for error messages related to plugin loading (e.g., duplicate IDs, missing services, class loading errors). - Ensure the plugin JAR is in ~/.kortty/plugins/ and contains META-INF/services/de.kortty.plugin.terminaleffects.TerminalEffectPlugin. - Use Plugins > Terminal Effects > Reload to refresh the plugin list.

Log file size: - kortty.log grows during the day and is rolled over at midnight, and archives are deleted according to Keep logs. You can safely delete the log files while KorTTY is closed.

Master password recovery: - There is no recovery for a forgotten master password. If you lose it, delete master.key and credentials.xml, restart KorTTY, and set a new password.