DD-SSH

DD-SSH is a clean cross-platform SSH client and session manager built with Qt/C++/CMake/libssh.

The goal is simple:

Open the app. Double-click a saved server. Get a real SSH 
terminal. Work. 

DD-SSH is designed for practical sysadmin use: saved sessions, one portable JSON config, known-host checking, password/private-key authentication, xterm.js terminal tabs, and safe config handling.

---

Current status

Development checkpoint: dev 0.1.6.1.1 Codename: Andromeda Milestone: MF 0.2 candidate — Real Terminal Foundation Current phase: README screenshots and Debian packaging tutorial polish

DD-SSH is now entering its first packaging phase. It is not a stable 1.0 release yet, but the core workflow is functional and has been validated on Linux, Windows 10, and Windows 11. Native Windows Debug/Release builds and a copied standalone Windows deployment folder have been tested with MSVC, Qt 6.11.1, Qt WebEngine/WebChannel/Positioning, vcpkg/libssh, and pkgconf.

The current documentation checkpoint consolidates three important Andromeda stabilization wins:

• dev 0.1.5.6 proved the Windows standalone deployment folder can run outside the build tree without manually extending PATH.
• dev 0.1.5.7 fixed portable known_hosts behavior so one shared dd-ssh.json can carry multiple legitimate host-key algorithms per host:port.
• dev 0.1.5.8 fixed a Windows/libssh handshake failure against newer OpenSSH servers that advertise ML-KEM/SNTRUP key-exchange algorithms before classic curve25519/ecdh algorithms.

The portable known-host model now supports multi-key storage per host:port:

• old single-key known-host entries are migrated when saved
• a new legitimate key algorithm is offered as Trust additional key instead of forcing Replace stored key
• true same-algorithm fingerprint mismatches still show the strong SSH host-key-changed warning
• Trust once continues for the current attempt without saving the new key

On Windows builds, DD-SSH applies a conservative libssh KEX override before ssh_connect() so affected Windows/vcpkg/libssh builds can connect to modern OpenSSH servers where the default algorithm proposal previously failed with Failed to construct client init buffer. The server-side workaround used during debugging is no longer required for the validated regression case.

The previous polish pass also added two user-safety clarifications:

• new saved sessions are stored only after a successful SSH authentication test
• closing DD-SSH with active SSH terminal tabs asks for confirmation before disconnecting them

On Windows, the first xterm.js terminal tab may take a few seconds while Qt WebEngine initializes; DD-SSH reports that startup state more clearly:

saved session → plaintext secret from dd-ssh.json → known_hosts 
check → SSH auth → xterm.js terminal → PTY resize → real shell 

Important session-save behavior

DD-SSH saves a new session only after a successful SSH authentication test.

If the host is unreachable, the port is wrong, the username/password is wrong, the private key is invalid, or the known-host check does not allow continuing, the session is not written to dd-ssh.json.

This prevents broken or unverified sessions from being saved as normal connection profiles.

Exit safety

If one or more SSH terminal tabs are still connected, closing the app with the window close button or File → Exit asks for confirmation before disconnecting them.

---

Screenshots

These screenshots show DD-SSH installed and running from the first Debian package experiment on Linux.

Welcome screen and saved sessions

The Welcome tab summarizes the current Andromeda milestone, available workflows, documentation entry points, and the saved-session sidebar. This view is useful as a quick project/status dashboard after installing the package.

Connected xterm.js SSH terminal

A saved session is opened as a real xterm.js terminal backed by a libssh shell channel. The terminal shows the connection state, target, local xterm.js renderer, PTY resize state, SSH authentication progress, and a live Ubuntu shell.

Edit saved session dialog

Saved sessions can be edited without retyping existing plaintext secrets. Leaving the password/private-key fields empty keeps the saved secret; entering a new password or key replaces it in dd-ssh.json.

Settings dialog

The Settings dialog exposes the active config path, app theme selection, terminal font settings, quick toolbar visibility, and rotating config-backup options. The config folder can be opened directly from here.

Dark theme terminal

DD-SSH can follow a dark Qt app theme while keeping the xterm.js terminal in its dark terminal style. This view shows the normal connected-session layout after theme changes are applied.

About dialog

The About dialog reports the current development version, codename, milestone, linked libssh backend version, and the exact config file path. It is the quickest sanity check after installing a new .deb package.

See Screenshots for the same gallery with longer descriptions.

---

Public alpha preparation

The current development line is preparing for a public alpha tag:

v0.2.0-alpha — Andromeda MF 0.2 — Real Terminal Foundation 

Before tagging, run:

• Linux Packaging Guide
• Debian Package Tutorial
• Screenshots
• Public Alpha Checklist
• Test Matrix
• Windows Build Guide
• Windows Deployment Guide
• Release Notes Draft

GitHub issue templates are included for bug reports, terminal issues, config/recovery issues, and feature requests.

---

Big security warning

Early DD-SSH builds intentionally support portable plaintext secrets.

That means saved passwords and private keys may be stored inside:

dd-ssh.json 

under:

"secrets": {
  "mode": "plain-v1", "items": {}
}

This is convenient for portability, but it is not secure for untrusted machines.

Do not commit your real dd-ssh.json to Git. Do not share it publicly. Use this mode only on trusted computers.

Future versions may add encrypted/master-password storage while preserving the current session reference structure.

See Security Notes.

---

What works now

Sessions and config

• Saved sessions loaded from dd-ssh.json
• One portable JSON config containing sessions, known_hosts, settings, metadata, and plaintext secrets
• Password authentication
• Private-key authentication
• Known-host trust handling
• Create/edit/delete saved sessions
• Duplicate username@host:port warning when saving sessions
• Double-click saved session opens xterm.js terminal by default
• Manual auth test remains available from the Session/context menu

Terminal

• Local bundled xterm.js renderer through Qt WebEngine
• No CDN dependency for terminal assets
• FitAddon + SSH PTY resize sync
• Password and private-key terminal sessions
• Reconnect after disconnect/reboot
• Terminal lifecycle cleanup
• Tested terminal apps:
  • htop
  • nano
  • vim
  • top
  • clear
  • stty size

Settings and UI

• Cross-platform app icon integration
• Qt window icon resource
• Windows .ico / .rc executable icon prep
• Linux PNG icon resources for future .desktop packaging
• macOS .icns and .iconset prep for future app bundles
• App theme: System / Light / Dark
• Terminal font family and size for newly opened terminal tabs
• Optional quick action toolbar
• Settings saved to dd-ssh.json
• File menu config actions:
  • Open Config Folder
  • Export Config
  • Import Config
  • Restore Latest Backup
  • Exit

Windows validation

• Native Windows build confirmed using MSVC x64 and Ninja
• Qt 6.11.1 MSVC 2022 64-bit tested with WebEngine, WebChannel, and Positioning
• libssh provided by vcpkg
• pkgconf used for current CMake/libssh discovery
• Windows config path uses AppData/Local style location via Qt
• xterm.js terminal, SSH connection, and htop were confirmed working on Windows
• First xterm/WebEngine terminal startup may be slower than Linux; later terminals are faster
• RAM usage is higher on Windows because Qt WebEngine embeds a Chromium-based engine

See Windows Build Guide.

Config safety

• Linux default config path:

~/.config/DD-LAB/DD-SSH/dd-ssh.json 

• Rotating backups before config saves
• Import creates pre-import backup
• Restore latest valid backup
• Corrupt config recovery dialog
• Corrupt config is never overwritten automatically
• Create fresh config option moves corrupt config aside first

---

What does not exist yet

DD-SSH is intentionally still limited. Not implemented yet:

• Encrypted secrets / master password
• SSH agent support
• Keyboard-interactive auth polish
• SFTP
• Split panes
• Multi-Exec command sending
• Keep-alive settings
• Portable mode next to binary
• Custom config path picker
• macOS validation pass
• Final signed installers / official repositories
• Signed releases
• Full public release process

---

Quick start for testers

1. Build

On Debian/Ubuntu/Linux Mint style systems:

sudo apt update sudo apt install -y \
  build-essential \ cmake \ ninja-build \ git \ pkg-config \ qt6-base-dev \ 
  qt6-base-dev-tools \ qt6-tools-dev \ qt6-tools-dev-tools \ qt6-webengine-dev \ 
  libssh-dev
cmake -S . -B build -G Ninja cmake --build build ./build/dd-ssh 

See Building and Windows Build Guide.

2. Create a session

Use:

Session → New Session 

Enter host, port, username, and auth method. After successful auth, DD-SSH saves the session to dd-ssh.json.

3. Open terminal

Double-click a saved session in the sidebar.

Expected result: an xterm.js terminal opens and connects to the saved SSH target.

4. Test terminal

whoami hostname stty size htop nano 
/tmp/dd-ssh-test.txt vim /tmp/dd-ssh-test.txt clear exit 

5. Backup/export config

Use:

File → Export 
Config... 

Exported config may contain plaintext passwords and private keys.

---

Main use cases

Use case: everyday SSH access

Save frequently used SSH targets once, then double-click from the sidebar to open a terminal tab.

Use case: portable personal SSH profile

Copy dd-ssh.json to another trusted machine and keep sessions, known_hosts, settings, passwords, and private keys together.

Use case: quick terminal health check

Open a session and run:

uptime df -h free -m systemctl status nginx --no-pager 

Use case: recovery after broken config

If dd-ssh.json becomes invalid, DD-SSH warns, refuses to overwrite it, lists backups, and lets the user restore the latest valid backup or create a fresh config.

Use case: public alpha testing

Run the test matrix in Test Matrix, report failures, and include OS/build details.

More examples: Use Cases.

---

Documentation map

Start here:

• Getting Started
• User Guide
• Use Cases
• Features and Limitations
• Known Limitations
• Config Management
• Config Format
• Security Notes
• Architecture
• Building
• Windows Build Guide
• Windows Deployment Guide
• Roadmap
• Test Matrix
• Public Alpha Checklist
• Release Notes Draft
• Changelog

---

Codename roadmap

0.0.x — Launchpad / early prototype 
history 0.1.x — Andromeda / current MF 0.2 candidate line 0.2.x — Orion 0.3.x — Vega 
0.4.x — Cassiopeia 1.0.x — Apollo 

Current line: 0.1.x Andromeda.

---

Project philosophy

Fast to open. Fast to connect. Easy to understand. Easy to back 
up. Portable when needed. Hard to accidentally destroy things. 

DD-SSH should stay focused. Early versions intentionally avoid SFTP, split panes, cloud lock-in, telemetry, and bloated enterprise dashboards.

Debian package quick path

The first local .deb packaging workflow is documented in detail in Debian Package Tutorial.

Short version:

./scripts/linux-build-release.sh ./scripts/linux-package-deb.sh 
sudo apt install ./dist/deb/dd-ssh_0.1.6.1.1_amd64.deb dd-ssh 

The package installs the app, desktop launcher, icons, README, license, Markdown documentation, and screenshots. It does not package your personal dd-ssh.json config.

---

MIT License

Copyright (c) 2026 Dalibor Klobučarić

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

DD-SSH Architecture

DD-SSH is built as a small layered Qt/C++ application.

High-level layers

+------------------------------------------------------------+
| UI Layer | MainWindow, ConnectDialog, SettingsDialog, WebTerminalTab |
+------------------------------------------------------------+
| Core Layer | ConfigManager, KnownHostsManager, SessionProfile |
+------------------------------------------------------------+
| SSH Layer | SshSession, SshShellWorker |
+------------------------------------------------------------+
| Terminal Layer | xterm.js in Qt WebEngine, TerminalBridge |
+------------------------------------------------------------+
| Config File | dd-ssh.json |
+------------------------------------------------------------+ 

Main UI classes

MainWindow

Responsibilities:

• Main window layout
• Menus
• Optional quick toolbar
• Sidebar session list
• Terminal tabs
• File config actions
• Session actions
• Settings dialog entry
• About dialog
• Config recovery warning

MainWindow coordinates behavior but should not contain low-level SSH protocol details.

ConnectDialog

Shared dialog with explicit modes:

Manual Connect New Saved Session 
Edit Saved Session 

SettingsDialog

Edits settings stored under settings in dd-ssh.json:

• Appearance
• Terminal font
• Config backup policy
• Quick toolbar visibility

WebTerminalTab

xterm.js terminal tab.

Responsibilities:

• Load local xterm.js resources
• Own terminal UI controls
• Forward keyboard/paste/Ctrl+C to SSH worker
• Receive output and write to xterm.js
• Track connected/disconnected state
• Reconnect using same saved session
• Handle PTY resize notifications

BasicTerminalTab

Temporary QWidget input/output fallback used for debugging.

Core classes

ConfigManager

Responsibilities:

• Locate config file
• Load/save JSON
• Load/save sessions
• Load/save settings
• Manage plaintext secrets
• Export/import config
• Restore latest backup
• Create rotating backups
• Inspect corrupt config
• Create fresh default config

KnownHostsManager

Responsibilities:

• Store known-host trust records in dd-ssh.json
• Compare host key fingerprints
• Trust unknown hosts when user confirms
• Refuse changed-host silent acceptance
• Avoid overwriting invalid config

SessionProfile

Value object representing one saved session:

id name group host port username auth type 
secret_ref/key_ref 

SSH classes

SshSession

Manual/auth-test style wrapper around libssh connection/auth logic.

SshShellWorker

Runs an interactive SSH shell channel in a worker thread.

Responsibilities:

• Connect
• Known-host/auth support through supplied values
• Open PTY
• Open shell
• Read remote output
• Write queued input
• Resize PTY
• Disconnect cleanly
• Emit lifecycle signals

Terminal bridge

TerminalBridge

Qt WebChannel bridge between JavaScript/xterm.js and C++.

Used for:

• Input from browser terminal to C++
• Resize notifications from xterm.js to C++

Threading model

GUI thread: - Main window - Settings - Menus - Sidebar - Qt 
WebEngine widget - xterm.js rendering Worker thread: - SSH shell 
connect/auth/read/write loop - PTY resize handling - disconnect cleanup 

The SSH read loop must not block the GUI thread.

Terminal data flow

User input:

xterm.js onData() → 
TerminalBridge → WebTerminalTab → SshShellWorker input queue → libssh channel write → 
remote shell 

Remote output:

remote shell → libssh channel read → SshShellWorker output 
signal → WebTerminalTab → xterm.write(data) 

PTY resize:

Qt/WebEngine size change → xterm FitAddon → 
cols/rows → TerminalBridge terminalResized() → SshShellWorker resizePty() → 
ssh_channel_change_pty_size() 

Config safety design

Config writes should be safe:

• Use backups when enabled.
• Do not overwrite invalid JSON automatically.
• Preserve corrupt configs as .corrupt-* when creating fresh config.
• Create pre-import/pre-restore backups before replacing active config.

Future architecture direction

Likely future classes:

SessionManager MultiExecManager KeepAliveManager 
ConfigPathManager ThemeManager 

Do not add large responsibilities to MainWindow when a focused class is appropriate.

Building DD-SSH

DD-SSH is a Qt 6 / C++ / CMake / libssh project.

Linux dependencies

Debian/Ubuntu/Linux Mint style systems:

sudo 
apt update sudo apt install -y \
  build-essential \ cmake \ ninja-build \ git \ pkg-config \ gdb \ qtcreator \ 
  qt6-base-dev \ qt6-base-dev-tools \ qt6-tools-dev \ qt6-tools-dev-tools \ 
  qt6-webengine-dev \ libssh-dev

If CMake reports missing Qt WebEngine:

sudo apt install qt6-webengine-dev 

If CMake reports missing libssh:

sudo apt install 
libssh-dev 

Configure and build

cmake -S . -B build -G Ninja cmake --build build ./build/dd-ssh 

Clean rebuild:

cmake --build 
build --clean-first 

Qt Creator

Open CMakeLists.txt in Qt Creator, configure a Qt 6 kit, then build and run.

Current runtime requirements

• Qt Widgets
• Qt WebEngineWidgets
• Qt WebChannel
• libssh

xterm.js assets are bundled as Qt resources under:

resources/xterm/ 

No CDN should be required for terminal rendering.

Current tested platform

Linux remains the primary development platform. Windows native Debug/Release build validation, standalone deploy-folder validation, known-host portability, and Windows libssh KEX compatibility have been validated on real Windows 10/11 machines. macOS still needs dedicated validation.

Version identity

The About dialog reads version strings from CMakeLists.txt:

set(DD_SSH_VERSION_STRING "dev 0.1.6.1.1") 
set(DD_SSH_CODENAME_STRING "Andromeda") set(DD_SSH_MILESTONE_STRING 
"MF 0.2 candidate") 

Every generated checkpoint should update the version string.

---

Windows native build

A native Windows build has been validated during the Andromeda line using MSVC, Ninja, Qt 6.11.1 MSVC 2022 64-bit, Qt WebEngine/WebChannel/Positioning, vcpkg libssh, and vcpkg pkgconf.

See the dedicated guide:

• Windows Build Guide

Short version:

cmake -S . -B build-win 
-G Ninja ^
  -DCMAKE_BUILD_TYPE=Debug ^ -DCMAKE_PREFIX_PATH=C:\Qt\6.11.1\msvc2022_64 ^ 
  -DCMAKE_TOOLCHAIN_FILE=C:\dev\vcpkg\scripts\buildsystems\vcpkg.cmake ^ 
  -DPKG_CONFIG_EXECUTABLE=C:\dev\vcpkg\installed\x64-windows\tools\pkgconf\pkgconf.exe
cmake --build build-win 

Release build testing should use build-win-release and -DCMAKE_BUILD_TYPE=Release.

Icon resources

DD-SSH icon assets live under:

resources/icons/ resources/windows/ resources/macos/ 

The Qt app icon is embedded as a Qt resource and loaded from:

:/icons/dd-ssh.png 

Windows executable icon integration uses:

resources/windows/dd-ssh.rc resources/windows/dd-ssh.ico 

macOS bundle icon prep uses:

resources/macos/dd-ssh.icns resources/macos/dd-ssh.iconset/ 

Linux packaging can later install the PNG size variants from resources/icons/ into the appropriate hicolor icon theme directories.

---

Windows deployment

After a Release build succeeds, see Windows Deployment Guide for the first windeployqt-based standalone deployment test and helper script:

scripts/windows-deploy-release.bat 

Linux Release/package helper

For the README screenshots and Debian packaging tutorial polish:

./scripts/linux-build-release.sh ./scripts/linux-package-deb.sh 

See docs/LINUX_PACKAGING.md.

Debian package tutorial

For the full .deb packaging/install/remove workflow, see Debian Package Tutorial.

DD-SSH Changelog

dev 0.1.6.1.1 — Andromeda

README screenshots and Debian packaging tutorial polish.

• Updated the project identity to dev 0.1.6.1.1.
• Added a README screenshot gallery using the Linux .deb validation screenshots.
• Added docs/SCREENSHOTS.md with descriptions for the Welcome screen, connected terminal, edit-session dialog, settings dialog, dark theme terminal, and About dialog.
• Added docs/DEBIAN_PACKAGE_TUTORIAL.md with a copy/paste workflow for building, inspecting, installing, testing, and removing the local .deb.
• Updated Linux packaging docs and test matrix to reflect that the first Debian package path was built, installed, launched, and visually validated.
• Updated the Debian package script default output version to dd-ssh_0.1.6.1.1_amd64.deb.
• Kept SSH/session/terminal/config runtime behavior unchanged in this documentation and packaging-polish checkpoint.

dev 0.1.6.1 — Andromeda

First Debian package experiment.

• Updated the project identity to dev 0.1.6.1.
• Added Linux CMake install rules for the DD-SSH binary, desktop launcher, hicolor icons, README, license, and Markdown documentation.
• Added scripts/linux-build-release.sh for a repeatable Linux Release build.
• Added scripts/linux-deploy-release.sh for a local Linux release staging folder.
• Added scripts/linux-package-deb.sh to generate the first .deb package with dpkg-deb.
• Added Debian maintainer hooks to refresh desktop and icon caches when available.
• Added docs/LINUX_PACKAGING.md and refreshed packaging documentation for the 0.1.6.x packaging phase.
• Kept SSH/session/terminal/config runtime behavior unchanged in this packaging checkpoint.

dev 0.1.5.9 — Andromeda

Stabilization docs and release polish.

• Updated the project identity to dev 0.1.5.9.
• Consolidated the successful Windows standalone deployment, known-host multi-key portability, and Windows libssh KEX compatibility results into the documentation set.
• Updated README, roadmap, test matrix, public alpha checklist, Windows build/deployment docs, troubleshooting, and known limitations to reflect the validated Windows 10 / Windows 11 / Linux status.
• Added a dedicated stabilization checkpoint report for the 0.1.5.6 → 0.1.5.8 validation sequence.
• Added a focused release checklist for future Andromeda public-alpha preparation.
• Kept SSH/session/terminal/config runtime behavior unchanged in this documentation checkpoint.

dev 0.1.5.8 — Andromeda

Windows libssh handshake compatibility polish.

• Updated the project identity to dev 0.1.5.8.
• Added a Windows-only libssh key-exchange compatibility override before ssh_connect().
• The Windows override limits libssh KEX negotiation to conservative algorithms already validated with Windows OpenSSH against OpenSSH 10 servers: curve25519-sha256, curve25519-sha256@libssh.org, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, and diffie-hellman-group14-sha256.
• Applied the compatibility override consistently to handshake tests, authentication tests, and real shell sessions.
• Added DD_SSH_LIBSSH_DEBUG=1 as a local diagnostic switch for libssh protocol verbosity.
• Added DD_SSH_DISABLE_WINDOWS_KEX_COMPAT=1 as a local escape hatch for comparing behavior with the compatibility override disabled.
• Added dedicated documentation for the real lab.dd-lab.hr:2231 regression case where Windows libssh failed with Failed to construct client init buffer while Linux DD-SSH and Windows OpenSSH worked.

dev 0.1.5.7 — Andromeda

Known-host multi-key portability polish.

• Updated the project identity to dev 0.1.5.7.
• Changed known-host storage from one key per host:port to multi-key storage under keys.
• Preserved compatibility with the old algorithm / fingerprint known-host format and migrates it on the next save.
• Added a separate Additional SSH host key decision path with Trust additional key, Trust once, and Cancel.
• Kept the strong SSH host key changed warning for true same-key-type fingerprint mismatches.
• Fixed the saved-session shell known-host decision flow so Trust once can continue the current shell-open attempt.
• Replaced scripts/windows-deploy-release.bat with the simpler working BAT validated during the Windows standalone deployment test.
• Added a dedicated known-host portability regression test note for the Windows 10 ECDSA vs Linux/Windows 11 ED25519 case.

dev 0.1.5.6 — Andromeda

Windows standalone deployment test.

• Updated the project identity to dev 0.1.5.6.
• Hardened scripts/windows-deploy-release.bat for the standalone Windows release-folder test.
• Added deployment sanity checks for the deployed executable, Qt platform plugin, Qt WebEngine runtime hints, libssh, OpenSSL, and zlib DLLs.
• Updated Windows deployment documentation for dist\windows-release, no-manual-PATH launch testing, and clean Windows 10 validation.
• Updated README, About/Welcome text, roadmap, known limitations, public alpha checklist, build docs, packaging notes, and test matrix for the 0.1.5.6 focus.
• Kept SSH authentication, terminal runtime, config import/export/recovery, icon resources, and exit-safety behavior unchanged.

dev 0.1.5.5 — Andromeda

Exit safety and user guide polish.

• Added application-level exit safety for active SSH terminal sessions.
• Closing the main window with active SSH connections now asks before disconnecting them.
• File → Exit now uses the same close protection as the window close button.
• Added user-facing documentation explaining that new sessions are saved only after successful SSH authentication.
• Updated README, user guide, troubleshooting, feature list, test matrix, and release-prep notes.
• Kept SSH authentication, xterm.js terminal runtime, config import/export, icons, and Windows deployment logic unchanged.

dev 0.1.5.4 — Andromeda

Windows deployment experiment.

• Added docs/WINDOWS_DEPLOYMENT.md with the first windeployqt-based deployment workflow.
• Added scripts/windows-deploy-release.bat as an experimental helper for creating a standalone Windows release folder.
• Documented copying vcpkg runtime DLLs such as libssh/OpenSSL/zlib into the deployment folder.
• Documented testing the deployed app outside the build tree and without Qt/vcpkg PATH setup.
• Updated Windows build/release docs, roadmap, test matrix, and public-alpha checklist for deployment validation.
• Kept SSH/session/terminal runtime behavior and the updated icon resources unchanged.

dev 0.1.5.3 — Andromeda

WebEngine startup polish.

• Added a visible terminal startup notice while the local xterm.js / Qt WebEngine renderer is preparing.
• Added clearer UI states for preparing/loading/ready/failed terminal renderer startup.
• Documented the Windows first-terminal startup delay as expected Qt WebEngine initialization behavior.
• Kept xterm.js terminal behavior, SSH/session logic, and icon resources otherwise unchanged.

dev 0.1.5.2 — Andromeda

App icon integration.

• Added cross-platform icon resources generated from the uploaded DD-SSH master PNG.
• Added Qt resource icons under :/icons/.
• Set the Qt application/window icon from :/icons/dd-ssh.png.
• Added Windows .ico and .rc resources for the .exe icon.
• Added Linux PNG icon size variants for future desktop packaging.
• Added macOS .iconset and .icns prep for future app bundle packaging.
• Updated CMake integration for Windows and macOS icon resources.
• No SSH/session/terminal runtime logic changes are intended in this checkpoint.

dev 0.1.5.1 — Andromeda

Windows build documentation and release build test preparation.

• Documented the first native Windows build path using MSVC x64, CMake, Ninja, Qt 6.11.1 MSVC 2022 64-bit, Qt WebEngine/WebChannel/Positioning, vcpkg libssh, and vcpkg pkgconf.
• Added docs/WINDOWS_BUILD.md with Debug and Release build commands.
• Documented Windows-specific observations: first WebEngine terminal startup delay, higher RAM usage from Qt WebEngine/Chromium, Qt cache folder, and AppData config path.
• Updated README, Welcome screen, Building docs, Test Matrix, Roadmap, and Public Alpha Checklist with Windows validation status.
• Added .gitignore coverage for Windows/MSVC local build artifacts.
• No SSH/session/terminal runtime logic changes are intended in this checkpoint.

dev 0.1.5.0 — Andromeda

Public alpha release preparation.

• Added docs/PUBLIC_ALPHA_CHECKLIST.md as the final pre-alpha gate.
• Added docs/RELEASE_NOTES_v0.2.0-alpha.md draft.
• Added docs/KNOWN_LIMITATIONS.md for public tester visibility.
• Added GitHub issue templates for bug reports, terminal issues, config/recovery issues, and feature requests.
• Added pull request template with project safety checklist.
• Updated README, Welcome screen, and test matrix for public alpha preparation.

dev 0.1.4.9 — Andromeda

Focus: Public alpha documentation pass.

• Rebuilt README as a public-alpha oriented project entry point.
• Added comprehensive documentation index.
• Added Getting Started guide.
• Added User Guide.
• Added Use Cases document.
• Added Features and Limitations document.
• Added Config Management document.
• Added Troubleshooting document.
• Expanded Architecture, Config Format, Security Notes, Roadmap, Building, Packaging, Release Process, and Test Matrix docs.
• Updated Welcome/About phase text to documentation pass.
• No SSH/session/terminal runtime logic changes are intended in this checkpoint.

dev 0.1.4.8 — Andromeda

Focus: Config import/export/restore polish.

• Added File-menu config actions: Open Config Folder, Export Config, Import Config, Restore Latest Backup, and Exit.
• Export Config copies the active dd-ssh.json to a user-selected path.
• Import Config validates the selected JSON file, warns before replacement, creates a pre-import backup, then reloads settings and saved sessions.
• Restore Latest Backup restores the newest valid dd-ssh.json.bak-* backup and moves the previous active config aside as dd-ssh.json.pre-restore-*.

dev 0.1.4.7 — Andromeda

Focus: Quick toolbar visibility polish.

• Hides quick action toolbar by default.
• Adds Settings option to show/hide quick action toolbar.
• Persists toolbar setting under settings.behavior.show_quick_toolbar.

dev 0.1.4.6 — Andromeda

Focus: Session menu and dialog mode polish.

• File menu reserved for app/config actions.
• Session menu owns New Session, Connect / Auth test, and Edit selected session.
• ConnectDialog has Manual Connect, New Saved Session, and Edit Saved Session modes.

dev 0.1.4.5.1 — Andromeda

Focus: Config recovery actions.

• Added Continue read-only.
• Added Restore latest valid backup.
• Added Create fresh config.
• Corrupt config files are preserved as .corrupt-*.

dev 0.1.4.5 — Andromeda

Focus: Config recovery guard.

• Invalid/non-object dd-ssh.json is not overwritten automatically.
• Startup recovery warning lists backups and can open config folder.

dev 0.1.4.4 — Andromeda

Focus: App theme foundation.

• Added app appearance setting: System / Light / Dark.
• Theme applies to Qt app chrome, not xterm.js terminal.

dev 0.1.4.3 — Andromeda

Focus: Codename roadmap alignment.

• Reframed 0.1.x as Andromeda / MF 0.2 candidate line.
• Kept Launchpad as 0.0.x early-prototype history.

dev 0.1.4.2 — Andromeda

Focus: Config path and backup policy implementation.

• Linux path casing changed to DD-LAB/DD-SSH.
• Implemented rotating config backups before saves.

dev 0.1.4.1 — Andromeda

Focus: Settings dialog sizing polish.

• Settings dialog opens at a readable default size.

dev 0.1.4.0 — Andromeda

Focus: Settings foundation.

• Added Settings dialog.
• Added terminal font settings.
• Added config path display.
• Added backup policy settings.
• Added plaintext secrets warning.

dev 0.1.3.9 — Andromeda

Focus: Andromeda test matrix documentation.

• Added test matrix for Real Terminal Foundation validation.

dev 0.1.3.8 — Andromeda

Focus: Terminal UI and status cleanup.

• Improved terminal header/state labels.
• Shortened terminal action labels.
• Improved status feedback.

dev 0.1.3.7 — Andromeda

Focus: Reconnect disconnected terminal.

• Added Reconnect action for disconnected xterm.js terminal tabs.

dev 0.1.3.6 — Andromeda

Focus: Terminal lifecycle polish.

• Added close confirmation for active SSH tabs.
• Added connected/disconnected tab markers.
• Improved remote disconnect/reboot handling.

dev 0.1.3.5 — Andromeda

Focus: Welcome and changelog polish.

• Updated Welcome screen.
• Added codename roadmap.

dev 0.1.3.4 — Andromeda

Focus: Double-click opens terminal.

• Saved session double-click opens xterm.js terminal by default.
• Auth test remains in context menu.

dev 0.1.3.3 — Andromeda

Focus: Terminal compatibility checkpoint.

• Added codename/milestone display.
• Added reset local terminal action.
• Confirmed terminal app compatibility direction.

dev 0.1.3.2.2 — Andromeda

Focus: Local xterm resource path fix.

• Fixed Qt resource path so bundled xterm.js/FitAddon load locally.

dev 0.1.3.1 — Andromeda

Focus: xterm fit + SSH PTY resize.

• Added FitAddon.
• Added terminal resize reporting to SSH worker.
• Remote stty size follows window size.

dev 0.1.3.0 — Andromeda

Focus: First xterm.js terminal renderer.

• Added first xterm.js renderer path through Qt WebEngine.

dev 0.1.2.x — Launchpad-to-Andromeda bridge

• Added basic saved-session SSH shell channel.
• Added web terminal fallback.
• Added paste/input dispatch fixes.
• Added focus polish.

dev 0.1.1.x — Launchpad

• Added saved sessions.
• Added plaintext secrets.
• Added connect from saved session.
• Added edit/delete session.
• Added duplicate target warning.

dev 0.1.0.x — Launchpad

• Initial Qt GUI skeleton.
• Manual connection dialog.
• SSH handshake/auth tests.
• known_hosts storage.

Codename roadmap

0.0.x — Launchpad / early prototype 
history 0.1.x — Andromeda / current MF 0.2 candidate line 0.2.x — Orion 0.3.x — Vega 
0.4.x — Cassiopeia 1.0.x — Apollo 

DD-SSH Config Format

DD-SSH uses one primary JSON config file:

dd-ssh.json 

Linux default path:

~/.config/DD-LAB/DD-SSH/dd-ssh.json 

Windows and macOS use Qt's platform-specific application config location through QStandardPaths::AppConfigLocation.

Top-level structure

{
  "app": {}, "settings": {}, "groups": [], 
  "sessions": [], "known_hosts": {}, "secrets": {}, 
  "metadata": {}
}

Example

{ "app": { 
    "name": "DD-SSH", "config_version": 1
  },
  "settings": { "appearance": { "app_theme": 
      "system"
    },
    "terminal": { "font_family": "monospace", 
      "font_size": 14
    },
    "config_safety": { "backups_enabled": true, 
      "max_backups": 10
    },
    "behavior": { "double_click_action": 
      "open_terminal", "show_quick_toolbar": false
    }
  },
  "groups": [], "sessions": [ { "id": 
      "root-192-168-1-237-223", "name": "Local test 
      server", "group": "Lab", "host": 
      "192.168.1.237", "port": 223, "username": 
      "root", "auth": {
        "type": "password", "secret_ref": 
        "secret-root-192-168-1-237-223-password"
      }
    }
  ], "known_hosts": { "192.168.1.237:223": { "keys": { 
        "ssh-ed25519": "SHA256:example-ed25519", 
        "ecdsa-sha2-nistp256": "SHA256:example-ecdsa"
      },
      "first_seen": "2026-05-17T12:00:00Z", 
      "last_seen": "2026-05-17T12:30:00Z"
    }
  },
  "secrets": { "mode": "plain-v1", "items": { 
      "secret-root-192-168-1-237-223-password": {
        "type": "password", "value": 
        "plaintext-password"
      }
    }
  },
  "metadata": { "created_by": "DD-SSH"
  }
}

Settings

Appearance

"appearance": {
  "app_theme": "system"
}

Supported values:

system light 
dark 

This currently affects the Qt application chrome only. The xterm.js terminal theme is intentionally unchanged.

Terminal

"terminal": {
  "font_family": "monospace", "font_size": 14
}

Terminal font settings apply to newly opened xterm.js tabs.

Config safety

"config_safety": {
  "backups_enabled": true, "max_backups": 10
}

When enabled, DD-SSH creates rotating dd-ssh.json.bak-* backups before saves.

Behavior

"behavior": {
  "double_click_action": "open_terminal", 
  "show_quick_toolbar": false
}

double_click_action is currently expected to be open_terminal.

Known hosts

Starting with dev 0.1.5.7, DD-SSH stores known hosts as multiple trusted host keys per host:port. This is required for one portable dd-ssh.json to work across platforms because different libssh/OS combinations may negotiate different legitimate server host-key algorithms.

Current format:

"known_hosts": {
  "138.2.166.222:223": { "keys": { "ssh-ed25519": 
      "SHA256:b2bVKCQSkPXuvXn4blGPV91iuJ5ySA8PqrBsI/8i5hs", 
      "ecdsa-sha2-nistp256": 
      "SHA256:tXwRSs3yDB71wdVX8Cnj57dmCszCgtU1kIHnDS9i19w"
    },
    "first_seen": "2026-05-20T20:00:00Z", "last_seen": 
    "2026-05-20T20:30:00Z"
  }
}

Legacy format is still accepted and migrated on save:

"known_hosts": {
  "138.2.166.222:223": { "algorithm": "ssh-ed25519", 
    "fingerprint": 
    "SHA256:b2bVKCQSkPXuvXn4blGPV91iuJ5ySA8PqrBsI/8i5hs"
  }
}

Decision rules:

• no entry for host:port → unknown host prompt
• same key type and same fingerprint → trusted
• new key type for an already-known host:port → Trust additional key prompt
• same key type but different fingerprint → strong SSH host key changed warning

Sessions

A session describes a connection target and auth method.

Password session:

{
  "id": "server-1", "name": "Server 1", 
  "group": "Lab", "host": "192.168.1.237", 
  "port": 223, "username": "root", "auth": {
    "type": "password", "secret_ref": 
    "secret-server-1-password"
  }
}

Private-key session:

{ 
  "id": "server-key", "name": "Server Key", 
  "group": "Lab", "host": "192.168.1.222", 
  "port": 223, "username": "root", "auth": {
    "type": "key", "key_ref": 
    "secret-server-key"
  }
}

Secrets

Early DD-SSH builds use:

"secrets": {
  "mode": "plain-v1", "items": {}
}

Password secret:

"secret-server-password": {
  "type": "password", "value": 
  "plaintext-password"
}

Private-key secret:

"secret-server-key": {
  "type": "private_key", "value": "-----BEGIN 
  OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----\n"
}

Sessions reference secrets. Secrets are not stored directly inside the session object.

This is intentional because future encrypted storage can replace the secrets backend without changing saved session structure.

known_hosts

Known-host records are stored separately from sessions.

Deleting a session does not automatically delete known_hosts.

Reason: several sessions may point to the same host/port with different usernames or auth methods.

Import/export behavior

Import/export operates on the whole config file.

Import replaces:

sessions secrets known_hosts settings 
metadata 

Before import, DD-SSH creates a pre-import backup of the active config.

Corrupt config behavior

If dd-ssh.json is invalid JSON or not a JSON object, DD-SSH refuses to overwrite it automatically.

Recovery options:

Continue read-only Restore 
latest valid backup Create fresh config Open config folder 

Corrupt files are preserved as:

dd-ssh.json.corrupt-<timestamp> 

DD-SSH Config Management

DD-SSH is built around one primary file:

dd-ssh.json 

This file is intended to be portable, human-readable, and easy to back up.

Default paths

Linux:

~/.config/DD-LAB/DD-SSH/dd-ssh.json 

Windows/macOS:

Qt 
QStandardPaths::AppConfigLocation 

The exact path is shown in:

Help → About DD-SSH Tools → Settings 

Config folder

Open it from:

File → 
Open Config Folder 

Backups

When enabled in Settings, DD-SSH creates backups before saving.

Backup names look like:

dd-ssh.json.bak-20260517-204435-715 

Settings:

Tools → Settings → Config safety 

Options:

Enable config backups 
before save Keep last N backups 

Export

File → Export Config... 

Exports the active dd-ssh.json to a user-selected path.

Warning: exported configs may contain plaintext passwords and private keys.

Import

File → Import Config... 

Import flow:

1. User selects JSON file. 2. DD-SSH validates that 
it is valid JSON. 3. DD-SSH validates that the root is a JSON object. 4. DD-SSH warns 
that current sessions/secrets/known_hosts/settings will be replaced. 5. DD-SSH 
creates a pre-import backup of the active config. 6. DD-SSH copies the imported file 
as active dd-ssh.json. 7. DD-SSH reloads settings and session list. 

Restore latest backup

File → Restore Latest 
Backup... 

Restore flow:

1. 
DD-SSH finds newest valid dd-ssh.json.bak-* file. 2. DD-SSH asks for confirmation. 3. 
Current active config is moved aside as dd-ssh.json.pre-restore-*. 4. Backup is 
copied back as dd-ssh.json. 5. Settings and session list reload. 

Corrupt config recovery

If active config is invalid, DD-SSH does not overwrite it.

The recovery dialog offers:

Open config folder Continue read-only Restore latest valid 
backup Create fresh config 

Continue read-only

Starts the app with default in-memory settings and an empty session list if needed. Save operations must not silently overwrite the corrupt file.

Restore latest valid backup

Moves corrupt config aside and restores the latest valid backup.

Create fresh config

Moves corrupt config aside and creates a new empty default dd-ssh.json.

Manual safety commands

Before risky tests:

cp ~/.config/DD-LAB/DD-SSH/dd-ssh.json 
~/.config/DD-LAB/DD-SSH/dd-ssh.json.manual-good chmod 600 
~/.config/DD-LAB/DD-SSH/dd-ssh.json.manual-good 

Validate JSON:

jq . ~/.config/DD-LAB/DD-SSH/dd-ssh.json 
>/dev/null && echo "JSON OK" 

List backups:

ls -la ~/.config/DD-LAB/DD-SSH/dd-ssh.json* 

DD-SSH Debian Package Tutorial

Checkpoint: dev 0.1.6.1.1 — Andromeda
Goal: build, package, install, test, and remove the first DD-SSH .deb package.

This tutorial is the practical copy/paste path for creating a local Debian package from the DD-SSH source tree.

The package produced by this checkpoint is a system-runtime package. It installs the DD-SSH binary, desktop file, icons, README, license, Markdown documentation, and screenshots. It expects Qt/libssh runtime libraries from the Linux distribution instead of bundling them inside the package.

0. Start from the project root

cd ~/DD-SSH git status 

The working tree should be clean before packaging a checkpoint.

1. Install build and packaging dependencies

On Debian, Ubuntu, Linux Mint, or LMDE-style systems:

sudo apt update sudo apt install -y \
  build-essential \ cmake \ ninja-build \ git \ pkg-config \ qt6-base-dev \ 
  qt6-base-dev-tools \ qt6-tools-dev \ qt6-tools-dev-tools \ qt6-webengine-dev \ 
  libssh-dev \ dpkg-dev \ fakeroot \ desktop-file-utils \ hicolor-icon-theme

Package names can vary slightly between distributions. If a package name is different on your distro, install the matching Qt 6 / Qt WebEngine / libssh development package.

2. Build the Linux Release binary

./scripts/linux-build-release.sh 

Expected binary:

build-linux-release/dd-ssh 

Optional local smoke test before packaging:

./build-linux-release/dd-ssh 

Check the About dialog and confirm it shows:

Version: dev 
0.1.6.1.1 Codename: Andromeda 

3. Build the .deb

./scripts/linux-package-deb.sh 

Expected output:

dist/deb/dd-ssh_0.1.6.1.1_amd64.deb 

The script stages the package with cmake --install, writes Debian control metadata, copies maintainer hooks, calculates installed size, and builds the package with dpkg-deb.

4. Inspect the package

dpkg-deb -I dist/deb/dd-ssh_0.1.6.1.1_amd64.deb 

List the package contents:

dpkg-deb -c 
dist/deb/dd-ssh_0.1.6.1.1_amd64.deb | less 

Useful paths to verify:

/usr/bin/dd-ssh 
/usr/share/applications/dd-ssh.desktop /usr/share/icons/hicolor/*/apps/dd-ssh.png 
/usr/share/doc/dd-ssh/README.md /usr/share/doc/dd-ssh/docs/LINUX_PACKAGING.md 
/usr/share/doc/dd-ssh/docs/DEBIAN_PACKAGE_TUTORIAL.md 
/usr/share/doc/dd-ssh/docs/screenshots/*.png 

5. Install locally

sudo apt install 
./dist/deb/dd-ssh_0.1.6.1.1_amd64.deb 

Run from terminal:

dd-ssh 

The desktop launcher should also appear in the application menu after the desktop database/icon cache refresh.

6. Smoke-test the installed app

Minimum test pass:

[ ] DD-SSH starts from terminal with `dd-ssh` [ ] 
app icon appears [ ] About shows dev 0.1.6.1.1 [ ] existing user config is preserved 
[ ] Settings opens and shows the config path [ ] saved session list loads [ ] 
password SSH login works [ ] private-key SSH login works [ ] xterm.js terminal opens 
[ ] `whoami` works [ ] `htop` works [ ] exit safety works when an SSH session is 
still connected 

7. Remove the package

sudo apt remove dd-ssh 

This removes the installed application files, but it does not remove your user config.

User config normally remains under the Qt standard config path, for example:

~/.config/DD-Lab/DD-SSH/dd-ssh.json 

Remove that manually only if you intentionally want to delete saved sessions/secrets/backups.

8. Build a different package version manually

The package script accepts an override:

DD_SSH_DEB_VERSION=0.1.6.1.1 ./scripts/linux-package-deb.sh 

It also accepts a manual dependency override if dpkg-shlibdeps cannot produce suitable dependencies for your distribution:

DD_SSH_DEB_DEPENDS="libc6, 
libstdc++6, libgcc-s1, libssh-4, libqt6core6, libqt6gui6, libqt6widgets6, 
libqt6webchannel6, libqt6webenginewidgets6" \
  ./scripts/linux-package-deb.sh 

9. What this package does not do yet

This first .deb does not yet provide:

• AppImage
• Snap/Flatpak
• bundled Qt runtime
• signed package/repository
• auto-update mechanism
• official PPA

Those are later packaging checkpoints.

DD-SSH Features and Limitations

Current feature set

Core app

• Qt/C++ desktop app
• Main window with sidebar and terminal tabs
• Menu-driven UI
• Optional quick action toolbar
• About dialog with version/codename/milestone/config path

Session management

• Saved sessions in dd-ssh.json
• Create saved session
• Edit saved session
• Delete saved session
• Duplicate target warning for same username + host + port
• Sidebar context menu
• Double-click opens xterm.js terminal

SSH/auth

• libssh integration
• SSH handshake
• Server banner display in auth tests
• Host key fingerprint display
• known_hosts trust flow
• Password authentication
• Private-key authentication

Terminal

• xterm.js through Qt WebEngine
• Local bundled xterm.js assets
• FitAddon
• SSH PTY resize sync
• Direct keyboard input
• Paste
• Ctrl+C
• Reconnect after disconnect
• App exit warning when active SSH terminal sessions are still connected
• Tested full-screen apps: htop, nano, vim, top

Config

• Single JSON config file
• Linux default path: ~/.config/DD-LAB/DD-SSH/dd-ssh.json
• Settings block
• sessions block
• known_hosts block
• secrets block
• metadata block
• Rotating backups
• Import/export
• New sessions are saved only after successful authentication
• Restore latest backup
• Corrupt config recovery

Settings

• App theme: System / Light / Dark
• Terminal font family
• Terminal font size
• Config backup enable/disable
• Max backup count
• Show/hide quick action toolbar

Known limitations

Security

• Passwords and private keys are stored in plaintext when saved.
• No master password yet.
• No encrypted secrets backend yet.
• No SSH agent support yet.

Terminal

• xterm.js terminal theme customization is intentionally deferred.
• Existing terminal tabs do not live-update font settings yet.
• Terminal preferences are still basic.

Platform support

• Linux is the primary development and regression-test platform.
• Native Windows build/runtime validation has started and is documented in docs/WINDOWS_BUILD.md.
• Windows app launch, SSH/xterm terminal, and htop were confirmed during the first MSVC/Qt/vcpkg test pass.
• Windows Release build metrics and deployment are still pending.
• macOS builds are intended but not validated yet.
• Packaging/installers are not ready.

Features not implemented

• Multi-Exec
• Keep-alive settings
• SFTP
• Split panes
• Portable mode next to binary
• Custom config path picker
• Encrypted config/secrets
• Import/export UI for individual sessions only

Public alpha meaning

DD-SSH is suitable for controlled public testing when clearly labeled as alpha:

Works for real 
SSH terminal usage. Stores secrets in plaintext. Use on trusted machines only. Report 
bugs with OS/build/config details. 

It is not yet a stable 1.0 daily-driver release.

Public alpha support docs

The repository now includes public-alpha preparation documents:

• docs/PUBLIC_ALPHA_CHECKLIST.md
• docs/RELEASE_NOTES_v0.2.0-alpha.md
• docs/KNOWN_LIMITATIONS.md
• GitHub issue templates under .github/ISSUE_TEMPLATE/

DD-SSH General Mindmap

Center

DD-SSH Clean cross-platform SSH 
client and session manager 

Current identity

Version: dev 0.1.6.1.1 Codename: Andromeda Milestone: MF 0.2 
candidate Phase: README screenshots and Debian packaging tutorial polish 

Main branches

Terminal

• xterm.js local renderer
• Qt WebEngine
• FitAddon
• PTY resize
• Ctrl+C
• Paste
• Reconnect
• htop/nano/vim/top/clear tested

Sessions

• Saved sessions
• Create
• Edit
• Delete
• Duplicate target warning
• Double-click opens terminal
• Manual auth test remains available

Config

• One dd-ssh.json
• Settings
• Sessions
• known_hosts
• Secrets
• Metadata
• Backups
• Import/export
• Recovery

Security

• known_hosts trust checking
• Changed host key should block
• Plaintext secrets warning
• No secrets in logs
• Future encryption planned

Settings

• App theme
• Terminal font
• Backup policy
• Quick toolbar visibility
• Config path display

Future

• Public alpha release
• Config path / portable mode
• Keep-alive
• Multi-Exec
• Packaging
• Encrypted secrets

Getting Started with DD-SSH

This guide explains how to build DD-SSH, create the first saved session, and open a terminal.

1. Build DD-SSH

On Debian/Ubuntu/Linux Mint style systems:

sudo apt update sudo apt install -y \
  build-essential \ cmake \ ninja-build \ git \ pkg-config \ qt6-base-dev \ 
  qt6-base-dev-tools \ qt6-tools-dev \ qt6-tools-dev-tools \ qt6-webengine-dev \ 
  libssh-dev
cmake -S . -B build -G Ninja cmake --build build ./build/dd-ssh 

If CMake cannot find Qt WebEngine, install qt6-webengine-dev.

Windows build note

A native Windows build path is documented separately because it requires MSVC, Qt MSVC, vcpkg libssh, and vcpkg pkgconf.

See: Windows Build Guide.

2. Confirm version

Open:

Help → About DD-SSH 

Expected checkpoint:

Version: dev 0.1.6.1.1 Codename: Andromeda 
Milestone: MF 0.2 candidate 

The About dialog also shows the active config path.

3. Create the first saved session

Open:

Session → New Session 

Enter:

Host Port Username Auth type Password or private key Session 
name Group (optional) 

New Session is intended to create a saved session after successful authentication.

The saved session appears in the left sidebar.

4. Open the terminal

Double-click the saved session in the left sidebar.

Expected result:

xterm.js terminal opens SSH authenticates using saved secret 
Remote shell appears 

Try:

whoami hostname pwd stty size htop nano /tmp/dd-ssh-test.txt 
vim /tmp/dd-ssh-test.txt clear exit 

5. Manual connect/auth test

Open:

Session → Connect / Auth test 

This is a manual connection test. Saving is optional.

The same action is available from the sidebar context menu as Run auth test.

6. Edit/delete sessions

Right-click a saved session in the sidebar:

Open xterm.js terminal Run auth 
test Open basic shell fallback Edit session Delete session 

Session editing preserves the existing secret if password/key fields are left empty.

Deleting a session does not delete known_hosts records automatically.

7. Settings

Open:

Tools → Settings 

Current settings include:

• Config path display
• App theme: System / Light / Dark
• Terminal font family and size for new tabs
• Config backup policy
• Optional quick action toolbar
• Plaintext secrets warning

8. Config export/import

Open:

File → 
Export Config... File → Import Config... File → Restore Latest Backup... File → Open 
Config Folder 

Config import/export operates on the full dd-ssh.json, not only settings.

That means exported configs may include plaintext passwords and private keys.

9. If config is corrupt

If dd-ssh.json is invalid, DD-SSH will not overwrite it automatically.

The recovery dialog offers:

Open config folder Continue read-only Restore latest valid 
backup Create fresh config 

Corrupt configs are moved aside as:

dd-ssh.json.corrupt-<timestamp> 

when a recovery action creates or restores a config.

DD-SSH Documentation Index

This directory contains the working documentation for DD-SSH.

User-facing docs

• Getting Started — first build, first session, first terminal
• User Guide — menus, workflows, sessions, settings, terminal use
• Use Cases — realistic ways DD-SSH is expected to be used
• Screenshots — visual overview of the installed DD-SSH app
• Features and Limitations — what works now, what does not
• Troubleshooting — common problems and recovery steps

Technical docs

• Architecture — UI/core/SSH/terminal/config layers
• Config Format — dd-ssh.json structure
• Config Management — backups, import/export, recovery
• Security Notes — plaintext secrets, known_hosts, future encryption
• Building — local build instructions
• Windows Build Guide — native Windows MSVC/Qt/vcpkg build notes
• Windows Deployment Guide
• Linux Packaging Guide — Linux packaging notes and first .deb package path
• Debian Package Tutorial — step-by-step .deb build/install/remove tutorial
• Windows libssh Handshake Compatibility Test — Windows KEX compatibility regression notes
• Packaging — future distribution notes

Project management docs

• Project Blueprint — product direction
• Roadmap — version plan and future features
• Test Matrix — manual validation checklist
• Changelog — checkpoint history
• Release Process — future release checklist
• Release Checklist — focused checkpoint smoke-test checklist
• Stabilization Checkpoint 0.1.5.9 — validated stabilization summary

Current checkpoint

Version: dev 0.1.6.1.1 Codename: Andromeda 
Milestone: MF 0.2 candidate Phase: README screenshots and Debian packaging tutorial 
polish 

Public alpha preparation

• Public Alpha Checklist
• Release Notes Draft: v0.2.0-alpha
• Windows Build Guide
• Windows Deployment Guide
• Linux Packaging Guide
• Debian Package Tutorial
• Screenshots
• Known Limitations
• Stabilization Checkpoint 0.1.5.9
• Release Checklist

GitHub issue templates live under .github/ISSUE_TEMPLATE/.

• Windows libssh handshake compatibility test

DD-SSH Known-host Portability Regression Test

Checkpoint: dev 0.1.5.9 — Andromeda
Focus: multi-key known-host storage for one portable dd-ssh.json

This test documents the real cross-platform issue found during the Windows standalone deployment test.

Test server

Host: 
138.2.166.222 Port: 223 

Confirmed server-side SSH host-key fingerprints:

ssh-ed25519: 
SHA256:b2bVKCQSkPXuvXn4blGPV91iuJ5ySA8PqrBsI/8i5hs ecdsa-sha2-nistp256: 
SHA256:tXwRSs3yDB71wdVX8Cnj57dmCszCgtU1kIHnDS9i19w 

Why this matters

The same SSH server can legitimately expose multiple host-key algorithms. Different OS/libssh combinations can negotiate different algorithms.

Observed behavior before dev 0.1.5.7:

Linux / 
Windows 11 negotiate ssh-ed25519 Windows 10 negotiates ecdsa-sha2-nistp256 

The old DD-SSH known-host model stored only one key per host:port, so replacing the stored key on one platform broke the same portable JSON on another platform.

Expected config model after 0.1.5.7

"known_hosts": {
  "138.2.166.222:223": { "keys": { "ssh-ed25519": 
      "SHA256:b2bVKCQSkPXuvXn4blGPV91iuJ5ySA8PqrBsI/8i5hs", 
      "ecdsa-sha2-nistp256": 
      "SHA256:tXwRSs3yDB71wdVX8Cnj57dmCszCgtU1kIHnDS9i19w"
    },
    "first_seen": "...", "last_seen": "..."
  }
}

Regression fixture A — ED25519-only config

Starting condition:

Known-host entry contains only 
ssh-ed25519. This works on Linux / Windows 11. This used to fail on Windows 10 when 
libssh negotiated ECDSA. 

Expected dev 0.1.5.7 behavior on Windows 10:

1. DD-SSH detects the host is known but the current key type is not saved yet.
2. Dialog title: Additional SSH host key.
3. Available choices include Trust additional key, Trust once, and Cancel.
4. Click Trust additional key.
5. Connection continues.
6. JSON now stores both ssh-ed25519 and ecdsa-sha2-nistp256 for the same host:port.
7. Copy the same JSON back to Linux / Windows 11.
8. Linux / Windows 11 connects without a reverse host-key warning.

Regression fixture B — ECDSA-only config

Starting condition:

Known-host entry contains only ecdsa-sha2-nistp256. 
This works on Windows 10. This used to fail on Linux / Windows 11 when libssh 
negotiated ED25519. 

Expected dev 0.1.5.7 behavior on Linux / Windows 11:

1. DD-SSH detects the host is known but the current key type is not saved yet.
2. Dialog title: Additional SSH host key.
3. Click Trust additional key.
4. Connection continues.
5. JSON now stores both keys.
6. Copy the same JSON back to Windows 10.
7. Windows 10 connects without a reverse host-key warning.

Validation result

Current validated result as of dev 0.1.5.9 docs:

ED25519-only starting config → Trust additional ECDSA on 
Windows 10: PASS ECDSA-only starting config → Trust additional ED25519 on 
Linux/Windows 11: PASS Final multi-key JSON reused across Windows 10, Windows 11, and 
Linux: PASS 

This confirms the shared dd-ssh.json portability goal for this regression case.

Trust once test

Starting condition:

Known-host entry contains one 
legitimate key. Current platform negotiates the other legitimate key. 

Expected behavior:

1. At the Additional SSH host key prompt, click Trust once.
2. The current auth/shell attempt continues.
3. dd-ssh.json is not permanently changed.
4. Restart DD-SSH and retry the same connection.
5. The additional-key prompt appears again.

True host-key-changed test

Use only a copied test JSON.

1. Edit one stored fingerprint for an existing key type.
2. Keep the key type the same.
3. Start DD-SSH and connect.
4. Expected result: strong SSH host key changed warning.
5. DD-SSH must not treat this as an additional-key case.

DD-SSH Known Limitations

Checkpoint: dev 0.1.6.1.1 — Andromeda

This document lists limitations that should be visible to testers. Nothing here is hidden or sugar-coated.

---

Security limitations

• Saved passwords may be stored in plaintext in dd-ssh.json.
• Saved private keys may be stored in plaintext in dd-ssh.json.
• There is no master password yet.
• There is no encrypted secrets store yet.
• There is no SSH agent integration yet.
• Use only on trusted machines.

---

Platform limitations

• Linux is the primary tested platform.
• Native Windows Debug and Release builds have been validated for app launch and SSH/xterm workflows. Standalone deployment-folder validation passed on real Windows 10/11 machines. Known-host multi-key portability and Windows libssh KEX compatibility have also been validated.
• macOS builds are planned but not fully validated.
• Installers are not ready; the current Windows target is a copied dist\windows-release folder.
• Code signing/notarization is not ready.

---

Feature limitations

Not implemented yet:

• SFTP
• Split panes
• Multi-Exec
• Keep-alive settings
• Portable mode next to binary
• Custom config path picker
• Encrypted config migration
• Advanced theme editor
• Terminal theme editor

---

Terminal limitations

The xterm.js terminal foundation is working, including PTY resize and several fullscreen terminal apps. Still, testers should report issues with:

• unusual key combinations
• function keys
• alternate keyboard layouts
• tmux/screen edge cases
• terminal resize edge cases
• copy/paste edge cases

---

Config limitations

Config import/export and recovery are implemented, but testers should handle real configs carefully because the file may contain plaintext secrets.

Always keep backups before testing import/export/recovery behavior.

---

Windows-specific alpha notes

The native Windows build and copied standalone deploy folder are confirmed to launch and run SSH/xterm workflows on Windows 10 and Windows 11. The current Windows work is still a deploy-folder workflow, not a full installer.

Known Windows alpha notes:

• Debug build startup is slower than Linux.
• First xterm.js terminal startup can take several seconds because Qt WebEngine initializes lazily.
• Subsequent terminal tabs are much faster.
• RAM usage can be hundreds of MB with an active xterm/WebEngine terminal because Qt WebEngine embeds Chromium components.
• Qt may create a cache folder under the DD-SSH AppData directory.
• The windeployqt deployment helper is validated for the current alpha workflow. A final installer is still future work.

Known-host portability note

dev 0.1.5.7 fixes the single-key known-host portability limitation found during Windows standalone testing. DD-SSH now accepts the legacy one-key format but saves known-host entries with a keys object so ED25519 and ECDSA host keys for the same host:port can coexist.

A true same-algorithm fingerprint mismatch is still treated as a strong host-key-changed warning.

DD-SSH Linux Packaging

Checkpoint: dev 0.1.6.1.1 — Andromeda
Phase: README screenshots and Debian packaging tutorial polish

This document describes the first Linux packaging path for DD-SSH. For the copy/paste packaging workflow, see Debian Package Tutorial.

The goal is not yet a perfect distribution-grade package. The goal is a practical first .deb that installs the tested DD-SSH binary, desktop launcher, icons, and documentation on Debian/Ubuntu/Mint-style systems.

Packaging strategy

dev 0.1.6.1.1 uses a system-runtime Debian package:

• DD-SSH is built locally with CMake.
• The package installs /usr/bin/dd-ssh.
• The package installs a desktop launcher under /usr/share/applications.
• PNG icons are installed into the hicolor icon theme.
• Markdown docs are installed under /usr/share/doc/dd-ssh.
• Qt/libssh runtime libraries are expected from the Linux distribution packages.

This keeps the first .deb small and easy to inspect. A later packaging checkpoint may add an AppDir/AppImage or a bundled runtime strategy if needed.

Required packaging tools

On Debian/Ubuntu/Mint/LMDE-style systems, install the normal build dependencies first. For packaging, these tools are also useful:

sudo apt install dpkg-dev fakeroot desktop-file-utils 
hicolor-icon-theme 

dpkg-dev provides dpkg-deb and dpkg-shlibdeps. The packaging script uses dpkg-shlibdeps when available to detect runtime library dependencies from the built binary.

Build a Release binary

From the project root:

./scripts/linux-build-release.sh 

The default output is:

build-linux-release/dd-ssh 

You can test it directly:

./build-linux-release/dd-ssh 

Create the first .deb

From the project root:

./scripts/linux-package-deb.sh 

Expected output:

dist/deb/dd-ssh_0.1.6.1.1_amd64.deb 

Inspect the package metadata:

dpkg-deb -I 
dist/deb/dd-ssh_0.1.6.1.1_amd64.deb 

List package contents:

dpkg-deb -c dist/deb/dd-ssh_0.1.6.1.1_amd64.deb 

Install locally

sudo apt 
install ./dist/deb/dd-ssh_0.1.6.1.1_amd64.deb 

Then run:

dd-ssh 

The desktop menu should also show DD-SSH under a network/remote-access category after the desktop database refreshes.

Remove

sudo apt remove 
dd-ssh 

This removes the installed application files. It does not delete the user config file. Per-user config remains in the normal Qt standard path, such as:

~/.config/DD-Lab/DD-SSH/dd-ssh.json 

Important security note

Do not package a real dd-ssh.json. Early DD-SSH builds may store passwords/private keys in plaintext under secrets.mode = plain-v1. The .deb installs only application files and documentation.

Dependency notes

The package script tries to detect shared-library dependencies automatically with dpkg-shlibdeps. If that fails, it falls back to a conservative dependency list for Qt 6, Qt WebEngine, and libssh.

If the fallback list does not match a specific distribution, override it manually:

DD_SSH_DEB_DEPENDS="libc6, 
libstdc++6, libgcc-s1, libssh-4, libqt6core6, libqt6gui6, libqt6widgets6, 
libqt6webchannel6, libqt6webenginewidgets6" ./scripts/linux-package-deb.sh 

Validation result

The first .deb package path has been exercised by building the package, installing it locally, launching DD-SSH from the installed binary, opening a saved session, opening the Settings dialog, switching the app theme, and checking the About dialog. Screenshots from that validation pass are stored under docs/screenshots and summarized in Screenshots.

Test checklist

After installing the .deb, verify:

[ ] 
dd-ssh starts from terminal [ ] desktop launcher appears [ ] app icon appears [ ] 
About shows dev 0.1.6.1.1 [ ] settings dialog opens [ ] existing user config is 
preserved [ ] password SSH login works [ ] private-key SSH login works [ ] xterm.js 
terminal opens [ ] whoami works [ ] htop works [ ] exit safety still works with an 
active SSH session 

Current limitations

This first .deb is an experiment, not a final distribution policy package. It does not yet provide:

• AppImage
• Snap/Flatpak
• automatic update mechanism
• signed packages
• official repository/PPA
• bundled Qt runtime

Those can be added in later 0.1.6.x packaging checkpoints.

Packaging DD-SSH

Checkpoint: dev 0.1.6.1.1 — Andromeda
Phase: README screenshots and Debian packaging tutorial polish

DD-SSH has moved from source-build validation into the first packaging phase.

The first Linux package target is a practical .deb for Debian/Ubuntu/Mint/LMDE-style systems. Windows already has a validated deploy-folder flow; a Windows installer is planned later.

Current package targets

Linux

Current target:

• .deb package experiment

Scripts:

scripts/linux-build-release.sh scripts/linux-deploy-release.sh 
scripts/linux-package-deb.sh 

Documentation:

docs/LINUX_PACKAGING.md 

The first .deb installs DD-SSH under the normal /usr layout:

/usr/bin/dd-ssh 
/usr/share/applications/dd-ssh.desktop /usr/share/icons/hicolor/.../apps/dd-ssh.png 
/usr/share/doc/dd-ssh/ 

It uses system Qt/libssh runtime packages instead of bundling Qt libraries.

Windows

Current target:

• portable deploy folder

Script:

scripts/windows-deploy-release.bat 

Planned later:

• Inno Setup or NSIS installer
• Start Menu shortcut
• optional Desktop shortcut
• uninstaller
• signing later

macOS

Planned later:

• .app bundle
• .dmg
• signing/notarization when appropriate

Build first Linux .deb

From the project root on Linux:

./scripts/linux-build-release.sh 
./scripts/linux-package-deb.sh 

Expected output:

dist/deb/dd-ssh_0.1.6.1.1_amd64.deb 

Install locally:

sudo apt install 
./dist/deb/dd-ssh_0.1.6.1.1_amd64.deb 

Run:

dd-ssh 

Important packaging notes

DD-SSH uses Qt WebEngine. Packaging must preserve Qt WebEngine runtime compatibility.

xterm.js assets are bundled through Qt resources and should not require network access.

Config location

Do not package a real dd-ssh.json with secrets.

The app creates/uses a per-user config path through Qt standard paths.

Icons

The Linux .deb installs PNG icons into the hicolor icon theme and references dd-ssh from the .desktop file. Windows deployment preserves the embedded .exe icon generated from resources/windows/dd-ssh.rc. macOS packaging should include resources/macos/dd-ssh.icns inside the app bundle.

Future targets

Linux future work:

• AppImage
• Snap
• Flatpak maybe later

Windows future work:

• installer
• code signing later

macOS future work:

• .app bundle
• .dmg
• notarization later

DD-SSH Project Blueprint

Project summary

DD-SSH is a clean cross-platform SSH client and session manager.

Primary stack:

C++ Qt 6 CMake 
libssh xterm.js through Qt WebEngine JSON config 

Primary platforms:

Linux Windows macOS 

Current tested focus: Linux.

Product philosophy

Fast to open. Fast to connect. Easy to understand. Easy to 
sync. Easy to back up. Hard to accidentally destroy things. No unnecessary circus. 

What DD-SSH is

• Desktop SSH client
• Saved session manager
• xterm.js terminal frontend
• Single JSON config app
• Practical sysadmin tool
• Open-source project

What DD-SSH is not yet

• Stable 1.0 product
• SFTP client
• Split-pane terminal suite
• Cloud sync service
• Team collaboration system
• Encrypted secret vault
• Multi-exec power tool

Current Andromeda direction

The 0.1.x Andromeda line is building toward:

MF 0.2 — Real Terminal Foundation 

That means:

• Saved sessions work
• SSH auth works
• known_hosts works
• xterm terminal works
• PTY resize works
• terminal lifecycle works
• config safety exists
• public alpha docs exist

Core data model

dd-ssh.json is the source of truth for:

settings sessions 
known_hosts secrets metadata 

Secrets are currently plaintext under secrets.mode = plain-v1.

Architectural rules

• Do not put SSH protocol logic into UI classes when a core/ssh class can own it.
• Do not block the GUI thread with SSH read loops.
• Do not silently accept changed host keys.
• Do not write secrets to logs.
• Do not overwrite corrupt configs automatically.
• Do not change config format without updating docs.
• Keep terminal frontend replaceable enough for future changes.

Near-term goals

• Finish public alpha documentation
• Stabilize config workflow
• Prepare v0.2.0-alpha Andromeda

Later goals

• Custom config path / portable mode
• Keep-alive
• Multi-Exec
• Cross-platform packaging
• Encrypted secrets
• Public releases

DD-SSH Public Alpha Checklist

Checkpoint: dev 0.1.6.1.1 — Andromeda Milestone target: v0.2.0-alpha — Real Terminal Foundation

This checklist is the final pre-alpha gate. It is intentionally practical: run it on a real machine, with real saved sessions, before tagging a public alpha.

---

1. Build identity

• Clean build succeeds:

cmake --build build --clean-first 

• App launches:

./build/dd-ssh 

• Help → About DD-SSH shows:

Version: dev 0.1.6.1.1 Codename: Andromeda Milestone: MF 0.2 
candidate Current phase: README screenshots and Debian packaging tutorial polish. 

• Welcome tab opens and describes the current Andromeda status.

---

2. Config path and safety

• About dialog shows the Linux config path:

~/.config/DD-LAB/DD-SSH/dd-ssh.json 

• dd-ssh.json is valid JSON:

jq . ~/.config/DD-LAB/DD-SSH/dd-ssh.json >/dev/null 
&& echo "JSON OK" 

• Config file permissions are owner-readable/writable where supported:

stat -c '%a %n' 
~/.config/DD-LAB/DD-SSH/dd-ssh.json 

Preferred result on Linux:

600 .../dd-ssh.json 

• Settings save creates a backup file when backups are enabled.
• Backup rotation does not delete the active config.

---

3. Saved session workflow

• Session → New Session creates a saved password session.
• Session → New Session creates a saved private-key session.
• Double-clicking a saved session opens an xterm.js terminal.
• Session → Connect / Auth test still works for manual testing.
• Session → Edit selected session updates name/group/host/auth fields correctly.
• Deleting a session removes the session and orphan secret but preserves known_hosts.
• Duplicate username + host + port warning offers Update existing / Create copy / Cancel.

---

4. Terminal behavior

Run these in a password session and a private-key session:

whoami hostname pwd stty size ls -la clear htop nano 
/tmp/dd-ssh-alpha-test.txt vim /tmp/dd-ssh-alpha-test.txt top exit 

Expected:

• xterm.js local renderer is active.
• No CDN is required for xterm.js.
• ANSI color output renders correctly.
• stty size follows window resize.
• htop, nano, vim, top, and clear are usable.
• exit marks the tab disconnected.

---

5. Lifecycle behavior

• Disconnect button closes the shell cleanly.
• Reconnect button reconnects a disconnected tab.
• Closing an active tab asks for confirmation.
• Closing a disconnected tab does not show an active-session warning.
• External server reboot/disconnect is detected and cleaned up.
• After disconnect, remote input actions are disabled until reconnect.

---

6. Settings and appearance

• Settings opens from Tools → Settings.
• App theme System / Light / Dark works and persists.
• Terminal font size applies to newly opened terminal tabs.
• Optional quick action toolbar can be shown/hidden and persists.
• Plaintext secrets warning is visible in Settings.
• Open Config Folder opens the expected directory.

---

7. Config import/export/restore

• File → Export Config creates a valid JSON export.
• File → Import Config rejects invalid JSON.
• File → Import Config accepts valid exported config after confirmation.
• Import creates a backup of the previous active config.
• File → Restore Latest Backup restores a valid backup after confirmation.
• App reloads sessions/settings after import/restore.

---

8. Corrupt config recovery

Create a temporary backup first:

cp ~/.config/DD-LAB/DD-SSH/dd-ssh.json 
~/.config/DD-LAB/DD-SSH/dd-ssh.json.good 

Then corrupt the active file:

printf '{ invalid json\n' > 
~/.config/DD-LAB/DD-SSH/dd-ssh.json 

Expected:

• Startup shows a config recovery warning.
• Corrupt file is not overwritten automatically.
• Continue read-only opens the app without loading sessions.
• Restore latest valid backup moves corrupt config aside and restores backup.
• Create fresh config moves corrupt config aside and creates a default config.

Restore your real test config when finished:

cp ~/.config/DD-LAB/DD-SSH/dd-ssh.json.good 
~/.config/DD-LAB/DD-SSH/dd-ssh.json chmod 600 ~/.config/DD-LAB/DD-SSH/dd-ssh.json 

---

9. Documentation and public alpha readiness

• README describes current status and limitations.
• SECURITY_NOTES clearly warns about plaintext secrets.
• TEST_MATRIX is conservative and current.
• RELEASE_NOTES_v0.2.0-alpha.md is ready.
• GitHub issue templates exist.
• Known limitations are not hidden.

---

10. Final decision

Before tagging v0.2.0-alpha, answer honestly:

Can 
an external tester build DD-SSH, create a session, open xterm.js terminal, recover 
from config trouble, and understand the plaintext secret warning? 

If yes, Andromeda is ready for public alpha.

---

Windows regression validation

Before tagging public alpha, re-run or review the two Windows regressions fixed in the 0.1.5.x line:

[ ] 
Known-host multi-key portability: final JSON works on Windows 10, Windows 11, and 
Linux [ ] Windows libssh KEX compatibility: lab.dd-lab.hr:2231 connects without 
server-side workaround 

See:

• Known-host Portability Regression Test
• Windows libssh Handshake Compatibility Test

Windows build validation

Before tagging public alpha, run or review the Windows path in Windows Build Guide.

Minimum Windows public-alpha checklist:

[ ] Debug build still 
configures and builds with MSVC/Ninja [ ] Release build configures and builds [ ] App 
launches from build environment [ ] About and Settings open [ ] Config path uses 
AppData/Local/DD-LAB/DD-SSH [ ] Password SSH session opens xterm terminal [ ] htop 
works [ ] first terminal startup delay is documented [ ] RAM usage observation is 
documented [ ] deployment with the checked-in BAT script is tested from a copied 
`dist\windows-release` folder 

Icon validation

• App/window icon appears on Linux window manager.
• Windows .exe icon appears in Explorer/taskbar after build/deploy.
• macOS .icns resource is available for future app bundle packaging.

Windows standalone deployment validation

• scripts\windows-deploy-release.bat creates dist\windows-release.
• dist\windows-release\dd-ssh.exe launches from a new normal Command Prompt without manually adding Qt/vcpkg to PATH.
• The whole dist\windows-release folder launches on a clean Windows 10 machine without Qt/vcpkg/MSVC dev tools installed.
• On the clean machine, About, Settings, saved session creation, password SSH login, xterm.js terminal, whoami, htop, app icon, and exit safety are tested.

Exit safety validation

• Close main window with an active xterm terminal and confirm warning appears.
• Choose Cancel and confirm the SSH session remains connected.
• Choose Disconnect and Exit and confirm the app closes cleanly.
• Repeat through File → Exit.
• Confirm README/USER_GUIDE explain that failed authentication does not save a new session.

DD-SSH Release Checklist

Current target line: Andromeda / MF 0.2 candidate
Current checkpoint: dev 0.1.6.1.1

This checklist is shorter than the full public-alpha checklist. Use it before tagging any internal development checkpoint or before preparing v0.2.0-alpha.

1. Repository state

git status git log --oneline -5 

Expected:

working tree clean 
latest commit matches the intended checkpoint 

2. Version identity

Check:

grep 
"DD_SSH_VERSION_STRING" CMakeLists.txt 

Expected for this checkpoint:

set(DD_SSH_VERSION_STRING "dev 
0.1.6.1.1") 

Also verify in the app:

Help → About DD-SSH 

Expected:

Version: dev 0.1.6.1.1 Codename: Andromeda Milestone: MF 0.2 
candidate 

3. Linux smoke test

rm -rf build cmake -S . -B build -G Ninja cmake --build build 
./build/dd-ssh 

Minimum pass:

[ 
] app launches [ ] About shows expected version [ ] Settings opens [ ] saved session 
opens xterm terminal [ ] whoami works [ ] htop works [ ] disconnect/reconnect work 

4. Linux Debian package smoke test

For the README screenshots and Debian packaging tutorial polish:

./scripts/linux-package-deb.sh dpkg-deb -I 
dist/deb/dd-ssh_0.1.6.1.1_amd64.deb dpkg-deb -c dist/deb/dd-ssh_0.1.6.1.1_amd64.deb | 
head -50 

Optional install test on a disposable or safe Linux machine:

sudo apt install 
./dist/deb/dd-ssh_0.1.6.1.1_amd64.deb dd-ssh sudo apt remove dd-ssh 

Minimum pass:

[ ] .deb file is created [ ] 
package metadata looks sane [ ] package contains /usr/bin/dd-ssh [ ] package contains 
/usr/share/applications/dd-ssh.desktop [ ] package contains hicolor icons [ ] 
installed dd-ssh launches [ ] About shows expected version [ ] user config is 
preserved after install/remove 

5. Windows build smoke test

From x64 Native Tools Command Prompt for VS 2022:

cd C:\dev\DD-SSH rmdir /s /q build-win-release rmdir /s /q 
dist\windows-release cmake -S . -B build-win-release -G Ninja ^ 
-DCMAKE_BUILD_TYPE=Release ^ -DCMAKE_PREFIX_PATH=C:\Qt\6.11.1\msvc2022_64 ^ 
-DCMAKE_TOOLCHAIN_FILE=C:\dev\vcpkg\scripts\buildsystems\vcpkg.cmake ^ 
-DPKG_CONFIG_EXECUTABLE=C:\dev\vcpkg\installed\x64-windows\tools\pkgconf\pkgconf.exe 
cmake --build build-win-release scripts\windows-deploy-release.bat 

Minimum pass:

[ ] CMake finds MSVC compiler [ 
] CMake finds libssh through pkgconf/vcpkg [ ] Release exe links [ ] deployment 
folder is created [ ] deployed exe starts [ ] About shows expected version 

5. Windows deployed-folder smoke test

Open a normal Command Prompt, not the VS developer prompt:

cd /d 
C:\dev\DD-SSH\dist\windows-release dd-ssh.exe 

Minimum pass:

[ ] app starts without manually setting Qt/vcpkg 
PATH [ ] app icon appears [ ] Settings opens [ ] imported config loads [ ] saved 
session opens xterm terminal [ ] whoami works [ ] htop works [ ] closing with an 
active SSH session shows exit confirmation 

6. Regression checks

Known-host multi-key portability:

[ ] ED25519-only config can add ECDSA as Trust additional key [ 
] ECDSA-only config can add ED25519 as Trust additional key [ ] final JSON works on 
Windows 10, Windows 11, and Linux 

Windows libssh KEX compatibility:

[ ] lab.dd-lab.hr:2231 connects 
on Windows without server-side KEX workaround [ ] DD_SSH_DISABLE_WINDOWS_KEX_COMPAT=1 
can be used only for comparison/debugging 

7. Documentation checks

[ ] README current status is accurate [ 
] TEST_MATRIX reflects validated platforms conservatively [ ] CHANGELOG has the new 
checkpoint entry [ ] WINDOWS_DEPLOYMENT matches the checked-in BAT script [ ] 
KNOWN_LIMITATIONS does not hide unfinished items [ ] SECURITY_NOTES still warns about 
plaintext secrets 

8. Optional internal tag

git tag dev-0.1.5.9 git push origin dev-0.1.5.9 

Use public release tags only when the full public-alpha checklist passes.

DD-SSH v0.2.0-alpha — Andromeda

Codename: Andromeda
Milestone: MF 0.2 — Real Terminal Foundation
Release type: public alpha candidate notes

These notes are a draft for the first public alpha release. They should be reviewed and adjusted before creating a GitHub release/tag.

---

Summary

DD-SSH is a clean cross-platform SSH client and session manager built with Qt/C++/CMake/libssh.

The Andromeda alpha focuses on the first real terminal foundation:

saved session → known_hosts 
check → password/private-key auth → xterm.js terminal → PTY resize → shell work 

It is usable for real SSH testing on Linux, but it is not a stable 1.0 release.

---

Highlights

• Saved SSH sessions in one dd-ssh.json config file
• Password authentication
• Private-key authentication
• Known-host trust handling stored in the same config file
• Portable plaintext secrets mode: secrets.mode = "plain-v1"
• xterm.js terminal renderer bundled locally through Qt resources
• SSH PTY resize sync using xterm.js FitAddon
• Tested terminal programs: htop, nano, vim, top, clear
• Session create/edit/delete workflow
• Duplicate session warning for same username@host:port
• Reconnect after disconnect/reboot
• Config backups, import/export, restore latest backup
• Corrupt config recovery actions
• Settings foundation with app theme, terminal font size, and quick toolbar visibility

---

Security warning

This alpha can store saved passwords and private keys in plaintext inside dd-ssh.json.

Do not publish, share, or commit your real dd-ssh.json.

Use only on trusted machines.

Encryption/master-password support is planned for a later version.

---

Known limitations

• Linux is the primary tested platform so far
• Windows and macOS builds are not fully validated yet
• No encrypted secrets/master password yet
• No SSH agent integration yet
• No SFTP
• No split panes
• No Multi-Exec yet
• No official installers/packages yet
• No signed releases yet
• Terminal theme customization is intentionally deferred

---

Suggested tester flow

1. Build DD-SSH from source.
2. Create one password session.
3. Create one private-key session.
4. Open each saved session with double-click.
5. Run:

whoami 
hostname stty size htop nano /tmp/dd-ssh-test.txt vim /tmp/dd-ssh-test.txt clear 

6. Test disconnect/reconnect.
7. Export config.
8. Test corrupt config recovery on a copied config.
9. Report issues with OS, Qt version, libssh version, DD-SSH version, and steps to reproduce.

---

Release checklist

Before tagging this alpha, complete:

• docs/PUBLIC_ALPHA_CHECKLIST.md
• docs/TEST_MATRIX.md
• README final review
• SECURITY_NOTES final review
• GitHub issue templates review
• Fresh clone build test

---

Windows validation notes

During the Andromeda preparation line, DD-SSH was successfully built and launched natively on Windows using MSVC, Qt 6.11.1, Qt WebEngine/WebChannel/Positioning, vcpkg libssh, and vcpkg pkgconf. The dev 0.1.5.6 standalone deployment pass tracks windeployqt, vcpkg runtime DLL copying, no-manual-PATH launch testing, and clean Windows 10 deploy-folder validation.

The Windows build was able to open an SSH/xterm terminal and run htop.

Known Windows alpha caveats:

• first xterm terminal startup may be slower than Linux due to Qt WebEngine initialization
• RAM usage is higher than a native terminal-only app because Qt WebEngine embeds Chromium components
• deployment with windeployqt is still planned

DD-SSH Release Process

This process is still evolving.

Current next target

Potential next public tag:

v0.2.0-alpha — Andromeda 

Meaning:

Real Terminal 
Foundation public alpha 

Pre-release checklist

Before an alpha release:

• Version string updated in CMakeLists.txt
• About dialog shows correct version/codename/milestone
• README reflects current status
• SECURITY_NOTES warns about plaintext secrets
• TEST_MATRIX is current
• PUBLIC_ALPHA_CHECKLIST is completed
• RELEASE_NOTES_v0.2.0-alpha.md is reviewed
• GitHub issue templates are present
• CHANGELOG includes latest checkpoint
• Build works locally
• Password session test passes
• Private-key session test passes
• xterm terminal test passes
• PTY resize test passes
• htop/nano/vim/top/clear tests pass
• Remote reboot/reconnect test passes
• Config export/import/recovery tests pass

Suggested release note structure

DD-SSH v0.2.0-alpha — Andromeda This 
is a public alpha for Real Terminal Foundation testing. Highlights: - Saved SSH 
sessions - xterm.js terminal tabs - Password/private-key auth - known_hosts handling 
- PTY resize - Config import/export/recovery Security warning: - Saved 
passwords/private keys are plaintext in dd-ssh.json. Known limitations: - Linux 
tested most heavily - No encrypted secrets yet - No SFTP - No Multi-Exec yet 

Tagging

Example:

git 
tag -a v0.2.0-alpha -m "DD-SSH v0.2.0-alpha Andromeda" git push origin 
v0.2.0-alpha 

Do not tag until tests are confirmed.

---

Windows Release build gate

Before a public alpha tag that claims Windows support, perform the Windows Release build process from Windows Build Guide.

Record:

- Windows version - Qt version - vcpkg/libssh 
version - Release configure/build result - app startup time - first terminal startup 
time - second terminal startup time - RAM after Welcome screen - RAM after one xterm 
terminal 

Deployment/installer artifacts are not required for the first internal Windows validation, but public releases should eventually use windeployqt and a clean machine/runtime test.

---

Windows deployment folder test

Current stabilization checkpoint: dev 0.1.5.9 — stabilization docs and release polish.

Before a public alpha release that includes Windows notes:

1. Build Release on 
Windows. 2. Run scripts\windows-deploy-release.bat. 3. Start 
dist\windows-release\dd-ssh.exe from a normal Command Prompt. 4. Confirm About, 
Settings, xterm terminal, SSH login, htop, Disconnect, and Reconnect. 

See docs/WINDOWS_DEPLOYMENT.md for details.

DD-SSH Roadmap

Codename roadmap

0.0.x — Launchpad / early 
prototype history 0.1.x — Andromeda / current MF 0.2 candidate line 0.2.x — Orion 
0.3.x — Vega 0.4.x — Cassiopeia 1.0.x — Apollo 

Current line: 0.1.x — Andromeda

Goal: Real Terminal Foundation and public-alpha readiness.

Already implemented:

• Saved sessions
• One-file JSON config
• Plaintext portable secrets
• known_hosts handling
• Password/private-key auth
• Session CRUD
• xterm.js local terminal
• PTY resize
• Terminal lifecycle/reconnect
• Settings foundation
• App light/dark/system theme
• Config backup/recovery
• Config import/export/restore
• Documentation/test matrix

Remaining before public alpha tag:

• Final public-alpha checklist pass
• Confirm latest test matrix on Linux and Windows
• Optional screenshots
• Known limitations review
• Decide whether to tag dev-0.1.5.9 as an internal stabilization marker

Potential tag:

v0.2.0-alpha — Andromeda 

0.2.x — Orion

Focus: usability and session workflow polish.

Possible items:

• Better session grouping UI
• Search/filter saved sessions
• Session detail panel
• Duplicate session action
• More polished session edit flow
• Better tab title/status UX
• More robust reconnect options
• Config import/export UX refinements

0.3.x — Vega

Focus: portability and config location.

Possible items:

• Custom config path picker
• Portable mode next to executable
• Config file reload detection
• External sync conflict detection
• Better backup browser/restore picker
• Import/export individual sessions

0.4.x — Cassiopeia

Focus: connection reliability and admin workflow.

Possible items:

• Keep-alive per session
• Default keep-alive setting
• Dead connection detection polish
• SSH agent investigation
• Keyboard-interactive auth polish
• Better known_hosts management UI

0.5.x — Multi-Exec foundation

Focus: controlled multi-target command sending.

Required behavior:

• Select active terminal tabs
• Preview targets
• Send text only
• Send text + Enter
• Dangerous command warnings
• Local multi-exec log without secrets

Multi-Exec is powerful and risky. It should not be rushed.

0.9.x — Advanced theming / polish

Possible items:

• Terminal theme picker
• Custom app themes
• Custom terminal colors
• Theme import/export
• Live terminal preference updates

Terminal theme customization is intentionally low priority compared with app-level usability.

1.0.x — Apollo

Goal: first serious public release.

Expected before Apollo:

• Linux/Windows/macOS validation
• Packaging story
• Installer or portable builds
• Security notes finalized
• Known limitations clearly documented
• Encrypted secret storage decision made
• No known data-loss bugs

Current release-prep step

dev 0.1.6.1.1 adds README screenshots and a practical Debian packaging/install tutorial after the first .deb validation pass. dev 0.1.6.1 began the packaging phase with the first Debian package experiment. dev 0.1.5.9 is the stabilization docs and release polish checkpoint. It consolidates the 0.1.5.6 Windows standalone deployment pass, the 0.1.5.7 known-host multi-key portability fix, and the 0.1.5.8 Windows libssh KEX compatibility fix. The 0.1.5.x line prepares the repository for v0.2.0-alpha — Andromeda with public alpha docs, Windows Debug/Release/deploy-folder validation, release notes, known limitations, issue templates, cross-platform icon resources, WebEngine startup polish, and exit safety.

---

0.1.5.x Windows/public-alpha preparation

dev 0.1.5.0 — Public alpha release preparation dev 
0.1.5.1 — Windows build documentation and release build test dev 0.1.5.2 — App icon 
integration dev 0.1.5.3 — WebEngine startup polish dev 0.1.5.4 — Windows deployment 
experiment dev 0.1.5.5 — Exit safety and user guide polish dev 0.1.5.6 — Windows 
standalone deployment test dev 0.1.5.7 — Known-host multi-key portability polish dev 
0.1.5.8 — Windows libssh handshake compatibility polish dev 0.1.5.9 — Stabilization 
docs and release polish dev 0.1.6.1 — First Debian package experiment dev 0.1.6.1.1 — 
README screenshots and Debian packaging tutorial polish 

Windows/public-alpha scope:

• document native Windows MSVC/Qt/vcpkg build
• test Release build separately from Debug
• document first-terminal startup delay from Qt WebEngine
• document RAM expectations caused by Qt WebEngine/Chromium
• integrate app/window/exe icons
• test windeployqt deployment folder
• copy vcpkg runtime DLLs into the deployment folder
• run deployed app outside the build environment
• collect bugfixes before v0.2.0-alpha

DD-SSH Screenshots

Checkpoint: dev 0.1.6.1.1 — Andromeda
Phase: README screenshots and Debian packaging tutorial polish

This page contains the screenshot gallery used by the README. The screenshots were captured from the Linux .deb packaging validation pass and show the installed application running real saved sessions.

1. Welcome screen and saved sessions

The Welcome tab acts as a compact status page for the project. It shows the current Andromeda milestone, the active feature set, the menu layout, documentation pointers, bugfix focus, and the codename roadmap. The saved-session sidebar on the left shows grouped practical connection profiles loaded from dd-ssh.json.

2. Connected xterm.js SSH terminal

This is the main workflow: double-click a saved session and get a real shell. The terminal tab reports the connection target, xterm.js renderer status, PTY resize state, SSH worker lifecycle messages, authentication progress, and the final remote shell prompt.

3. Edit saved session dialog

The edit dialog supports practical saved-session maintenance. Existing password/private-key secrets can be kept by leaving the secret fields empty. Entering a new password or key replaces the saved secret in the portable JSON config.

4. Settings dialog

The Settings dialog exposes the active dd-ssh.json location, quick config-folder access, app theme selection, terminal font family and size for new tabs, quick-toolbar visibility, and rotating backup settings. The security note reminds users that early DD-SSH builds use plaintext portable secrets.

5. Dark theme terminal

DD-SSH supports a dark Qt application theme while the terminal remains in its dark xterm.js terminal style. This screenshot shows the normal connected terminal layout after changing the app theme.

6. About dialog

The About dialog is the fastest install sanity check. It shows the app name, current development version, codename, milestone, linked libssh backend version, and the exact config file path used by the installed build.

DD-SSH Security Notes

DD-SSH is currently an early public-alpha candidate. Security decisions are explicit and must remain visible to users.

Plaintext secrets

Current early builds use:

"secrets": {
  "mode": "plain-v1"
}

This means saved passwords and private keys may be stored in plaintext inside dd-ssh.json.

This is intentional for early portability, but it is insecure on untrusted machines.

User warning

The Settings dialog displays a plaintext warning. Keep it visible.

Recommended wording:

DD-SSH currently uses 
secrets.mode = plain-v1. Saved passwords and private keys are portable but stored in 
plaintext in dd-ssh.json. 

Never log secrets

Do not print:

• Password values
• Private key contents
• Full dd-ssh.json if it contains secrets
• Clipboard contents sent to terminal

Auth test output should say:

Saved password: loaded from JSON, hidden from display Saved 
private key: loaded from JSON, hidden from display 

known_hosts

Known-host verification is mandatory.

Rules:

• Unknown host must require user trust confirmation.
• Trusted host can continue when the current key type and fingerprint match a saved key.
• A new legitimate host-key algorithm for the same host:port must be treated as an additional key, not as an automatic replacement.
• Changed same-key-type fingerprint must not be silently accepted.
• Deleting a saved session must not automatically delete known_hosts.

Why not delete known_hosts with sessions?

Because multiple sessions can point to the same host/port with different usernames or auth methods.

Config backups

Config backups may also contain plaintext secrets.

Backups are useful, but they are sensitive files.

Treat these as secret-bearing files:

dd-ssh.json dd-ssh.json.bak-* dd-ssh.json.pre-import-* 
dd-ssh.json.pre-restore-* dd-ssh.json.corrupt-* 

Exported config

Exported config may contain passwords and private keys.

Do not share exported config publicly.

Git safety

Real config files must not be committed.

Recommended .gitignore patterns:

dd-ssh.json dd-ssh.json.* *.pem *.key id_rsa id_ed25519 

Future encrypted secrets

Future versions may support:

secrets.mode = encrypted master password key 
derivation AES-GCM or similar authenticated encryption 

Important principle:

Sessions should keep referencing 
secret_ref/key_ref. Only the secrets backend should change. 

Multi-Exec safety future note

Multi-Exec will be powerful and dangerous.

It must include:

• Target preview
• Send text only vs send + Enter
• Dangerous command warning
• Safe default action
• No hidden execution
• Local log without secrets

DD-SSH dev 0.1.5.9 Stabilization Checkpoint

Checkpoint: dev 0.1.5.9 — Andromeda
Focus: documentation, validation summary, and public-alpha release polish
Milestone: MF 0.2 candidate — Real Terminal Foundation

This checkpoint intentionally does not add new SSH/session/terminal runtime features. It records the successful stabilization work completed across the previous three checkpoints and aligns the documentation with the current tested state.

What this checkpoint locks in

dev 0.1.5.6 — Windows standalone deployment

Validated result:

Windows Release build works. The dist\windows-release folder 
can run outside the build tree. The app launches on real Windows 10 and Windows 11 
machines. Qt/vcpkg developer PATH is not required for the deployed folder test. 

Confirmed during testing:

• app launch
• app icon
• About dialog
• Settings dialog
• AppData config path
• Linux config import
• password SSH login
• xterm.js terminal
• whoami
• htop
• exit safety when connected sessions exist

dev 0.1.5.7 — Known-host multi-key portability

Validated result:

One 
portable dd-ssh.json can contain multiple legitimate host-key algorithms for the same 
host:port. 

Real regression case:

Host: 138.2.166.222 Port: 223 Linux / Windows 11 negotiated: 
ssh-ed25519 Windows 10 negotiated: ecdsa-sha2-nistp256 

Confirmed legitimate server fingerprints:

ssh-ed25519: 
SHA256:b2bVKCQSkPXuvXn4blGPV91iuJ5ySA8PqrBsI/8i5hs ecdsa-sha2-nistp256: 
SHA256:tXwRSs3yDB71wdVX8Cnj57dmCszCgtU1kIHnDS9i19w 

Expected post-fix behavior:

Additional legitimate key type → Trust 
additional key → save both keys. True same-algorithm fingerprint change → strong SSH 
host-key-changed warning. 

dev 0.1.5.8 — Windows libssh KEX compatibility

Validated result:

Windows 
DD-SSH can connect to a modern OpenSSH server that previously failed with: Failed to 
construct client init buffer. 

Real regression case:

Host: lab.dd-lab.hr Port: 2231 Forwarded target: 
192.168.1.233:223 Server banner: OpenSSH_10.0p2 Debian-7+deb13u2 

Observed before the fix:

Linux DD-SSH: works 
Windows OpenSSH: works and reaches authentication Windows DD-SSH dev build: fails 
during handshake Windows DD-SSH standalone build: fails during handshake 

A temporary server-side KEX restriction proved the root cause. After the app-side Windows KEX compatibility override, the server-side workaround is no longer required for the validated case.

Tested after the fix:

Windows 10: PASS Windows 11: PASS Linux: PASS 

Current state summary

Linux build/runtime: 
PASS Windows 10 build/runtime/deploy-folder: PASS Windows 11 
build/runtime/deploy-folder: PASS Portable config import Linux → Windows: PASS 
Known-host multi-key portability: PASS Windows libssh KEX compatibility: PASS macOS 
validation: TODO Installer/code signing: TODO Encrypted secrets: TODO 

Suggested tag

If the repository is clean and the latest build still passes, this checkpoint is a good candidate for a development tag:

git tag dev-0.1.5.9 git push origin dev-0.1.5.9 

This is not a public release tag. It is a stable internal development marker before the next public-alpha preparation pass.

DD-SSH Test Matrix

Checkpoint: dev 0.1.6.1.1 — Andromeda Milestone: MF 0.2 candidate — Real Terminal Foundation Phase: README screenshots and Debian packaging tutorial polish

This matrix tracks what has been confirmed manually, what is implemented but should be re-tested before a public alpha tag, and what is still planned.

Legend

PASS Confirmed working in manual testing. IMPLEMENTED Feature 
exists, but should be re-tested before public alpha tagging. PARTIAL Works, but needs 
polish or broader testing. NOT TESTED Important scenario not yet manually verified. 
TODO Not implemented yet. 

1. Build and identity

Area	Test	Expected result	Status	Notes
Build	cmake --build build --clean-first	Build completes and links dd-ssh	PASS	Re-tested frequently during development.
Linux Debian package	./scripts/linux-package-deb.sh	Creates dist/deb/dd-ssh_0.1.6.1.1_amd64.deb	PASS	First .deb package was built, installed, launched, and visually validated on Linux in dev 0.1.6.1.1.
Launch	./build/dd-ssh	App opens	PASS	Linux primary test platform.
Windows configure	CMake with MSVC/Qt/vcpkg/pkgconf	Configure completes	PASS	Confirmed on native Windows branch.
Windows Debug build	cmake --build build-win	dd-ssh.exe builds	PASS	Confirmed on native Windows.
Windows launch	build-win\dd-ssh.exe with Qt/vcpkg DLL paths	App opens	PASS	Confirmed; Welcome screen and UI visible.
Windows Release build	build-win-release	Release exe builds	PASS	Confirmed on native Windows before the deployment pass.
Windows libssh KEX compatibility	OpenSSH 10 server advertising ML-KEM/SNTRUP KEX first	DD-SSH reaches auth/shell flow on Windows 10/11	PASS	Validated on two Windows machines and one Linux machine after dev 0.1.5.8; server-side KEX workaround no longer required.
Windows deployment script	scripts\windows-deploy-release.bat after Release build	Creates dist\windows-release and starts deployed exe	PASS	Simple working BAT from the successful Windows standalone deployment test is now checked in.
Windows deployed launch	dist\windows-release\dd-ssh.exe from normal Command Prompt	App starts without Qt/vcpkg PATH	PASS	Confirmed on real Windows 10/11 machines during standalone deployment testing.
Clean Windows 10 deploy-folder test	Copy dist\windows-release to a clean Windows 10 machine	App launches without dev tools installed	PASS	App launches, icon appears, import/connect works, and xterm terminal is fast.
About	Help → About DD-SSH	Shows version/codename/milestone/config path	PASS	Verified after version/codename work.
Version	About dialog	Shows current checkpoint version	PASS	Should be checked after every patch.
Codename	About dialog	Shows Andromeda	PASS	Current 0.1.x codename line.
Welcome screen	First tab on startup	Shows current status/dashboard, not old skeleton text	PASS	Updated during docs/welcome polish.
Terminal startup notice	New terminal tab displays loading/startup state before xterm.js bridge is ready	User sees startup message instead of blank terminal during first WebEngine initialization	IMPLEMENTED	Added in dev 0.1.5.3; especially useful on Windows where first Qt WebEngine startup can be slower.
App icon resources	Build includes Qt/Windows/macOS/Linux icon assets	Window/exe/bundle icon resources exist	IMPLEMENTED	Added in 0.1.5.2; needs visual verification on Windows taskbar/Explorer and future Linux/macOS packaging.

2. Sessions and menus

Area	Test	Expected result	Status	Notes
Load sessions	Start app with valid config	Sidebar loads saved sessions	PASS	Tested repeatedly with real saved sessions.
New session	Session → New Session	Creates saved session after successful auth	PASS	Uses plaintext portable secret storage.
Failed new session save	Attempt New Session with failed auth	Session is not saved	IMPLEMENTED	Documented in dev 0.1.5.5; final pass should confirm wrong password/port does not create a sidebar entry.
Manual auth	Session → Connect / Auth test	Runs auth test; save optional	PASS	Old auth-test flow preserved.
Edit session	Session → Edit selected session / context menu	Edits selected saved session	PASS	Password/key can be kept or replaced.
Delete session	Context menu → Delete	Deletes session, preserves known_hosts	PASS	Orphan secret cleanup implemented.
Duplicate warning	Save same username+host+port	Offers update/copy/cancel	PASS	Manual save polish confirmed earlier.
Double-click	Double-click saved session	Opens xterm.js terminal	PASS	Default behavior since 0.1.3.4.
File menu	File menu	Config-level actions and Exit live here	IMPLEMENTED	Re-test after import/export and toolbar changes.
Session menu	Session menu	New/Connect/Edit session actions live here	PASS	Polished in 0.1.4.6.
Quick toolbar	Settings checkbox	Toolbar can be shown/hidden and persists	IMPLEMENTED	Needs final visual re-test after revised sizing patch.

3. Auth and known_hosts

Area	Test	Expected result	Status	Notes
Password auth	Saved password session	Auth succeeds	PASS	Tested with real LAN host.
Private-key auth	Saved key session	Auth succeeds	PASS	Tested with embedded plaintext private key from JSON.
Known host	Reconnect to same host	TRUSTED when fingerprint matches	PASS	Confirmed after known_hosts save/load.
Unknown host	First connect to new host	Prompts/trust flow works	PASS	Confirmed during first-connect tests.
Multi-key known host A	ED25519-only config on Windows 10 where libssh negotiates ECDSA	Offers Trust additional key, connects, saves both keys	PASS	Regression case: 138.2.166.222:223; confirms portable JSON works after adding ECDSA.
Multi-key known host B	ECDSA-only config on Linux/Windows 11 where libssh negotiates ED25519	Offers Trust additional key, connects, saves both keys	PASS	Reverse regression confirmed; same JSON works across Windows 10, Windows 11, and Linux after both keys are stored.
Trust once additional key	Additional key type prompt → Trust once	Opens shell/auth flow without saving JSON	IMPLEMENTED	Keep in final regression pass; primary Trust additional key path is validated.
Changed host	Same key type with different fingerprint	Must show strong host-key-changed warning	TODO	Needs deliberate edited-copy config test before stable release.

4. Terminal renderer and shell behavior

Area	Test	Expected result	Status	Notes
Renderer	Open terminal	Header says xterm.js ACTIVE local bundled renderer	PASS	Confirmed after Qt resource path fix.
Offline/local assets	Open terminal without CDN dependency	xterm.js still loads	PASS	Local bundled renderer confirmed active.
Basic command	whoami / hostname / pwd	Output appears	PASS	Confirmed.
Paste	Paste multiline commands	Commands execute	PASS	Fixed and confirmed.
Ctrl+C	ping 8.8.8.8, Ctrl+C	Ping stops	PASS	Confirmed.
PTY resize	stty size, resize window	rows/cols change	PASS	Confirmed with multiple window sizes.
htop	htop	Full-screen app renders	PASS	Confirmed.
nano	nano /tmp/dd-ssh-test.txt	Opens, text entry and Ctrl commands work	PASS	Confirmed, including Ctrl shortcuts.
vim	vim /tmp/dd-ssh-test.txt	Opens and works enough for manual testing	PASS	Confirmed.
top	top	Opens and updates	PASS	Confirmed.
clear	clear	Clears terminal	PASS	Confirmed.
Multiple terminal tabs	Open more than one saved session terminal	Inputs stay with correct session	PASS	Confirmed earlier with parallel tab testing.

5. Terminal lifecycle

Area	Test	Expected result	Status	Notes
Exit shell	exit	Terminal becomes disconnected	PASS	Confirmed.
Disconnect button	Click Disconnect	Session closes and controls update	PASS	Confirmed.
Remote reboot	Reboot server externally	DD-SSH detects disconnect and cleans up	PASS	Confirmed with real reboot test.
Reconnect	Click Reconnect after disconnect	Same tab reconnects using saved session	PASS	Confirmed after 0.1.3.7.
Close active tab	Click tab close while connected	Confirms before disconnecting	PASS	Confirmed in lifecycle polish.
Close active app window	Window close button / X while connected tabs exist	Confirms before disconnecting all active sessions and exiting	IMPLEMENTED	Added in dev 0.1.5.5; confirmed during deployed-folder testing.
File Exit with active sessions	File → Exit while connected tabs exist	Uses the same active-session confirmation as window close	IMPLEMENTED	Added in dev 0.1.5.5 via main window close event; include this in deployed-folder testing.
Close disconnected tab	Close after disconnect	Closes without active-session warning	IMPLEMENTED	Should be included in next final pass.

6. Settings and app UI

Area	Test	Expected result	Status	Notes
Open Settings	Tools → Settings	Dialog opens readable	PASS	Sizing polish added after visual issue.
App theme	System/Light/Dark	Qt app theme changes after OK and persists	PASS	Confirmed by user; app theme changes apply and persist.
Terminal font	Change font size	New terminal tabs use new font	PASS	Confirmed by user.
Backup setting	Enable/disable backups, max count	Setting is saved	PASS	Confirmed together with backup creation.
Open config folder	Settings/File action	Opens config folder	PASS	Confirmed during Windows/AppData validation path and Linux settings workflow.
Plaintext warning	Settings dialog	Orange plaintext secrets warning visible	PASS	Confirmed and intentionally kept.
Dark terminal	xterm terminal	Terminal remains dark independent of app theme	PASS	Intentional for now; xterm theming deferred.

7. Config safety and recovery

Area	Test	Expected result	Status	Notes
Default config	First run/no config file	Creates or uses healthy default config structure	IMPLEMENTED	Should be explicitly re-tested by moving config folder aside.
Backup before save	Save settings/session	dd-ssh.json.bak-* created	PASS	Confirmed.
Backup rotation	More backups than max count	Old backups are pruned	IMPLEMENTED	Needs explicit stress test.
Corrupt startup	Start with invalid config	Recovery dialog appears; file not overwritten	PASS	Confirmed.
Continue read-only	Recovery dialog	App opens without overwriting corrupt config	PASS	Confirmed in recovery flow.
Restore latest valid backup	Recovery dialog	Corrupt file moved aside, latest valid backup restored	PASS	Confirmed as part of recovery-actions testing if completed.
Create fresh config	Recovery dialog	Corrupt file moved aside, default config created	PASS	Confirmed as part of recovery-actions testing if completed.
Export config	File → Export Config	Valid JSON copied to chosen path	IMPLEMENTED	Needs explicit final public-alpha pass if not already tested.
Import invalid	Import invalid JSON	Import refused, active config unchanged	IMPLEMENTED	Needs explicit final public-alpha pass if not already tested.
Import valid	Import exported config	Pre-import backup created and config reloads	IMPLEMENTED	Needs explicit final public-alpha pass if not already tested.
Restore latest from File	File → Restore Latest Backup	Latest valid backup restored	IMPLEMENTED	Needs explicit final public-alpha pass if not already tested.

8. Documentation

Requirement	Status	Notes
README current	PASS	Public-alpha style README added.
Security warning visible	PASS	Plaintext secrets warning documented.
Config docs current	PASS	CONFIG_FORMAT updated.
Test matrix current	PASS	This file should stay conservative: do not mark untested items PASS.
Changelog current	PASS	CHANGELOG tracks development checkpoints.
Public alpha checklist	PASS	PUBLIC_ALPHA_CHECKLIST documents final pre-alpha gate.
Release notes draft	PASS	RELEASE_NOTES_v0.2.0-alpha.md added for alpha tagging.
GitHub issue templates	PASS	Bug, terminal, config/recovery, and feature request templates added.
Use cases documented	PASS	USE_CASES added.
Troubleshooting documented	PASS	TROUBLESHOOTING added.
Known limitations documented	PASS	Public alpha limitations documented.
Packaging docs	PARTIAL	Still planning-level, not release-proven.

9. Platform coverage

Platform	Status	Notes
Linux	PASS	Primary tested platform.
Windows	PASS	Native Windows Debug/Release builds, copied standalone deploy folder, SSH/xterm/htop, config import, exit safety, known-host portability, and libssh KEX compatibility have been validated on Windows 10/11. Installer packaging remains future work.
macOS	TODO	Build/runtime not validated yet.

9a. Windows validation details

Area	Test	Expected result	Status	Notes
MSVC	cl in x64 Native Tools prompt	Microsoft C/C++ compiler is available	PASS	MSVC x64 confirmed.
Qt WebEngine	Qt 6.11.1 MSVC 2022 64-bit	WebEngineWidgets found by CMake	PASS	Needed Qt Positioning dependency.
Qt WebChannel	Qt6WebChannelConfig.cmake exists	WebChannel bridge available	PASS	Confirmed in Qt install.
Qt Positioning	Qt6PositioningConfig.cmake exists	WebEngine dependency resolves	PASS	Added after first CMake failure.
vcpkg libssh	vcpkg install libssh:x64-windows	libssh installed	PASS	vcpkg reported successful install.
pkgconf	vcpkg pkgconf path passed to CMake	pkg_check_modules(libssh) works	PASS	CMake found libssh 0.12.0.
AppData config	First Windows launch	Config stored under AppData/Local/DD-LAB/DD-SSH	PASS	Windows path verified by app launch behavior.
Windows terminal	Saved session opens xterm	SSH terminal opens	PASS	Confirmed with real SSH session.
Windows htop	htop in terminal	Fullscreen terminal app renders	PASS	Confirmed by screenshot/test.
Windows startup/RAM	Task Manager observation	Record initial metrics	PARTIAL	Debug build showed several-second first terminal startup and ~350–380 MB RAM with WebEngine terminal. Release-build measurement should be recorded during deployment testing.
Windows deploy	Run outside build environment	App starts without developer PATH	PASS	Confirmed on real Windows 10/11 machines; app icon, config import, SSH connect, xterm terminal, whoami/htop, and exit safety validated.

10. Public alpha readiness summary

Requirement	Status	Notes
Core saved-session workflow	PASS	Create/edit/delete/open terminal tested.
Real terminal foundation	PASS	xterm.js, PTY resize, fullscreen apps tested.
Config safety foundation	PASS	Backup and corrupt config recovery exist.
Config import/export	IMPLEMENTED	Needs final focused pass before public alpha tag.
Settings foundation	PASS	Font/app settings exist; theme needs final confirmation if not already done.
Security posture documented	PASS	Plaintext secrets warning exists.
Windows/macOS validation	PARTIAL	Windows native Debug/Release/deploy-folder validation is now PASS; macOS remains pending.
Packaging/installers	TODO	Not part of current dev line.

11. Suggested final pre-alpha test pass

Before tagging an Andromeda public alpha, run this short pass:

cmake --build build --clean-first ./build/dd-ssh 

Then verify:

1. About shows the expected 
version/codename/milestone. 2. Saved password session opens xterm terminal. 3. Saved 
key session opens xterm terminal. 4. whoami, htop, nano, vim, top, clear work. 5. 
stty size changes after resizing the window. 6. Disconnect and Reconnect work. 7. 
Settings save and persist. 8. Config backup is created before save. 9. Corrupt config 
recovery still works. 10. Export/import/restore config actions pass a focused test. 
11. Windows Release build test records startup/RAM notes. 

DD-SSH Troubleshooting

Build problems

Qt6WebEngineWidgetsConfig.cmake missing

Install Qt WebEngine development package:

sudo apt 
install qt6-webengine-dev 

Then re-run CMake:

cmake -S . -B build -G Ninja 

libssh not found

Install libssh development package:

sudo apt install libssh-dev 

XKB warning during build

You may see a warning about XKB libraries. If the app builds and runs, it may be harmless.

To clean it up on Debian/Ubuntu/Mint:

sudo apt install libxkbcommon-dev libxkbcommon-x11-dev 
libxcb-xkb-dev 

Config problems

Where is my config?

Open:

Help → About DD-SSH 

or:

Tools → Settings 

Linux default:

~/.config/DD-LAB/DD-SSH/dd-ssh.json 

Config is corrupt

DD-SSH should show recovery dialog.

Options:

Continue read-only Restore latest 
valid backup Create fresh config Open config folder 

Manual validation:

jq . 
~/.config/DD-LAB/DD-SSH/dd-ssh.json >/dev/null && echo "JSON OK" 

Restore manually

cp 
~/.config/DD-LAB/DD-SSH/dd-ssh.json.bak-YYYYMMDD-HHMMSS-XXX 
~/.config/DD-LAB/DD-SSH/dd-ssh.json chmod 600 ~/.config/DD-LAB/DD-SSH/dd-ssh.json 

SSH problems

Wrong password

Use:

Session → Connect / Auth test 

Verify host, port, username, and password.

New session was not saved

DD-SSH saves a new session only after successful SSH authentication.

If the host is unreachable, the port is wrong, credentials are wrong, the private key fails, or the known-host decision does not allow continuing, DD-SSH will not write that session to dd-ssh.json.

This is expected behavior. First make the connection test pass, then save the session.

Private key auth fails

Check:

• Key file is valid
• Correct user
• Correct host/port
• Server has matching public key in authorized_keys
• Key content was saved correctly if using portable plaintext key storage

Windows handshake fails with "Failed to construct client init buffer"

dev 0.1.5.8+ includes a Windows-only libssh KEX compatibility override for newer OpenSSH servers that advertise ML-KEM/SNTRUP key-exchange algorithms before classic curve25519/ecdh algorithms.

If you need to compare behavior, run from CMD:

set 
DD_SSH_DISABLE_WINDOWS_KEX_COMPAT=1 dd-ssh.exe 

To enable libssh protocol verbosity while debugging:

set 
DD_SSH_LIBSSH_DEBUG=1 dd-ssh.exe 

Normal users should not need either variable.

Known-host warning

If host is unknown, DD-SSH asks for trust confirmation.

If host key changed, do not blindly accept. The server may have been reinstalled, DNS/IP may have changed, or there may be a security issue.

Terminal problems

htop/nano/vim looks broken

Check header says:

xterm.js ACTIVE - local bundled renderer 

If fallback is active, local xterm resources are not loading.

stty size does not change after resize

Run:

stty size 

Resize DD-SSH window and run again. If it does not change, PTY resize sync may be broken.

Terminal disconnected after reboot

This is expected when the remote host reboots.

Click:

Reconnect 

when the server comes back.

Import/export problems

Import rejected

DD-SSH requires imported config to be valid JSON and a JSON object.

Validate:

jq . imported-file.json 

Exported config contains secrets

Yes. Export copies full dd-ssh.json, including plaintext secrets.

Do not share exported configs publicly.

DD-SSH User Guide

Main window

DD-SSH uses a simple layout:

Left side: saved sessions from dd-ssh.json Right side: terminal 
tabs Bottom: status bar 

Double-click a saved session to open the default xterm.js terminal.

Menus

File

Config-level and app-level actions.

Open Config Folder Export 
Config... Import Config... Restore Latest Backup... Exit 

Session

SSH session workflow actions.

New Session Connect / Auth test Edit selected session 

Tools

Utility and app configuration actions.

Multi-Exec (placeholder for future work) Settings 

Help

About DD-SSH 

Session workflows

New Session

Creates a saved session after successful authentication.

Use this when adding a server you want to keep.

DD-SSH intentionally saves a new session only after the SSH handshake, known-host decision, and authentication test succeed. If the connection/authentication fails, the session is not saved. This keeps dd-ssh.json from filling with broken or unverified connection profiles.

Connect / Auth test

Runs a manual connection/authentication test. Saving is optional.

Use this when testing credentials, host keys, ports, or temporary access.

Edit selected session

Edits the currently selected sidebar session.

For password/private-key secrets:

Leave password/key 
empty to keep the existing saved secret. Enter a new password/key to replace the 
saved secret. 

Exit safety

If you close DD-SSH while one or more terminal tabs are still connected, the app asks before disconnecting them.

This applies to:

Window close button / X File 
→ Exit 

If you choose Cancel, DD-SSH stays open and all sessions remain connected.

If you choose Disconnect and Exit, DD-SSH requests disconnect on the active terminal sessions and then closes.

Sidebar context menu

Right-click a saved session:

Open xterm.js terminal Run auth test Open basic shell fallback 
Edit session Delete session 

The basic shell fallback is a debug/development fallback. The normal terminal is xterm.js.

Terminal tabs

The xterm.js terminal supports:

• Direct keyboard input
• Paste
• Ctrl+C
• PTY resize sync
• Full-screen terminal apps such as htop, nano, vim, top
• Reconnect after disconnect

Terminal buttons:

Ctrl+C Send interrupt to remote shell Paste Send clipboard text 
to terminal Clear Clear local terminal view Reset Reset local xterm renderer state 
Focus Focus terminal area Reconnect Reconnect after disconnect Disconnect Disconnect 
SSH shell 

Terminal lifecycle

When the remote shell exits, server reboots, or SSH transport drops, DD-SSH marks the tab disconnected and disables remote input actions.

After disconnect, use:

Reconnect 

The reconnect action uses the same saved session and plaintext secret.

Settings

Open:

Tools → Settings 

General

• Config path display
• Open config folder
• Double-click session action display
• Show quick action toolbar

Appearance

• System default
• Light
• Dark

This changes the Qt application chrome only. The xterm.js terminal theme remains dark for now.

Terminal

• Font family
• Font size

Font settings apply to newly opened xterm.js terminal tabs. Existing terminal tabs are not changed live yet.

Config safety

• Enable config backups before save
• Keep last N backups

Config import/export

Export Config

Copies the active dd-ssh.json to a user-selected path.

Warning: exported configs may contain plaintext passwords and private keys.

Import Config

Validates a selected JSON file, warns, creates a backup of the current active config, then replaces the active config.

Import replaces:

sessions secrets known_hosts settings 
metadata 

Restore Latest Backup

Restores the newest valid dd-ssh.json.bak-* file from the config folder.

The previous active config is moved aside as:

dd-ssh.json.pre-restore-<timestamp> 

DD-SSH Use Cases

This document explains what DD-SSH is useful for today and how each use case maps to current features.

Use case 1: Everyday SSH client

Goal: Open a saved server quickly and work in a normal terminal.

Workflow:

1. Save the server as 
a session. 2. Double-click it in the sidebar. 3. Work in the xterm.js terminal. 

Useful commands:

whoami 
hostname uptime df -h htop journalctl --no-pager -n 50 

Current support: works.

Use case 2: Personal portable SSH profile

Goal: Move one file to another trusted computer and keep sessions, settings, known_hosts, and secrets.

Workflow:

File → Export Config... Copy exported JSON to trusted machine 
File → Import Config... 

Important: the config may contain plaintext passwords and private keys.

Current support: works with plaintext secrets.

Use case 3: Password session

Goal: Save and open a server that uses password authentication.

Workflow:

Session → New Session Auth type: Password Save after 
successful auth Double-click session 

Current support: works.

Use case 4: Private-key session

Goal: Save and open a server that uses private-key authentication.

Workflow:

Session → New 
Session Auth type: Private key Select key file Save after successful auth 
Double-click session 

Current support: works.

Implementation note: early builds can store the private key content in plaintext under secrets.items.

Use case 5: Full-screen terminal app

Goal: Run interactive terminal apps like htop, nano, or vim.

Workflow:

htop nano /tmp/dd-ssh-test.txt vim /tmp/dd-ssh-test.txt 

Current support: works in Andromeda tests with local xterm.js + PTY resize.

Use case 6: Remote server reboot/disconnect

Goal: DD-SSH should not freeze or spin forever when the remote host disappears.

Workflow:

1. Open DD-SSH 
terminal. 2. Reboot server from another SSH connection. 3. Watch DD-SSH detect 
disconnect. 4. Click Reconnect after server returns. 

Current support: works.

Use case 7: Config recovery

Goal: Recover from invalid dd-ssh.json caused by manual edits or sync conflict.

Workflow:

DD-SSH detects invalid config Recovery dialog opens Choose 
restore latest backup or create fresh config 

Current support: works.

Use case 8: Public alpha testing

Goal: Validate DD-SSH behavior on real machines.

Run through:

• Build test
• Session create/edit/delete
• Password auth
• Private-key auth
• Terminal app tests
• Disconnect/reconnect tests
• Config export/import/recovery tests

Use TEST_MATRIX.md.

Use case 9: Future Multi-Exec

Goal: Send the same command to multiple open SSH tabs.

Example future workflow:

Open 3 server tabs Tools → Multi-Exec Command: uptime Targets: 
selected tabs Send text only or send + Enter 

Current support: not implemented. The menu item is a placeholder.

This feature is powerful and risky. It needs target preview, safe send modes, dangerous command warnings, and logging.

Windows Build Guide

Checkpoint: dev 0.1.5.9 — Andromeda
Purpose: document the native Windows build path, confirmed Release build procedure, and handoff to the standalone deployment test.

This guide documents the Windows setup that was validated during the Andromeda line. It is intentionally practical and conservative: first get a native Windows build running, then test runtime behavior, then later experiment with deployment/installer packaging.

---

Current Windows status

Confirmed during the first native Windows test pass:

[x] MSVC x64 compiler 
works [x] CMake configure works [x] Ninja build works [x] Qt app launches on Windows 
[x] Qt app theme follows Windows dark mode when set to System [x] Settings and 
Welcome screen open [x] SSH connection works [x] xterm.js local renderer works 
through Qt WebEngine [x] htop runs inside the Windows-built DD-SSH terminal [x] 
Release build succeeds with build-win-release 

Known Windows observations from the first Windows build tests:

- app startup is slower than Linux - first xterm.js terminal 
can take several seconds because Qt WebEngine/Chromium starts lazily - later terminal 
tabs open much faster - Task Manager showed roughly 350–380 MB RAM with a WebEngine 
terminal open - Qt may create a cache folder under the DD-SSH AppData location 

These are not currently treated as fatal bugs. They are expected side effects of using Qt WebEngine/xterm.js. Release builds should be used for standalone deployment testing.

---

Recommended Windows approach

Use a native Windows build, not WSL, for Windows validation.

Recommended stack:

Windows 10/11 Visual 
Studio 2022 Build Tools / MSVC x64 CMake Ninja Git for Windows Qt 6 MSVC 2022 64-bit 
Qt WebEngine Qt WebChannel Qt Positioning vcpkg libssh from vcpkg pkgconf from vcpkg 

Do not start with MinGW for this project. The first tested path uses MSVC.

---

1. Install Visual Studio C++ Build Tools

Install Visual Studio 2022 Build Tools or Visual Studio Community 2022.

Required workload:

Desktop development with C++ 

Required components:

MSVC 
v143/v144 x64 compiler toolset Windows 10/11 SDK C++ CMake tools for Windows 

Open:

x64 Native Tools Command 
Prompt for VS 2022 

Verify:

cl 
cmake --version ninja --version git --version 

Expected: cl prints Microsoft C/C++ compiler information, not 'cl' is not recognized.

---

2. Install Qt

Use Qt Maintenance Tool / Online Installer.

Tested path:

C:\Qt\6.11.1\msvc2022_64 

Required Qt components:

Qt 6.11.1 MSVC 2022 64-bit Qt 
WebEngine Qt WebChannel Qt Positioning 

Verify:

dir C:\Qt\6.11.1\msvc2022_64\lib\cmake\Qt6WebEngineCore dir 
C:\Qt\6.11.1\msvc2022_64\lib\cmake\Qt6WebEngineWidgets dir 
C:\Qt\6.11.1\msvc2022_64\lib\cmake\Qt6WebChannel dir 
C:\Qt\6.11.1\msvc2022_64\lib\cmake\Qt6Positioning 

If CMake says WebEngine is missing because Qt6Positioning could not be found, install Qt Positioning through the Maintenance Tool.

---

3. Install vcpkg, libssh, and pkgconf

From the x64 Native Tools prompt:

cd C:\ mkdir dev cd C:\dev git clone 
https://github.com/microsoft/vcpkg.git cd C:\dev\vcpkg bootstrap-vcpkg.bat vcpkg 
install libssh:x64-windows vcpkg install pkgconf:x64-windows 

Verify pkgconf path:

dir /s /b C:\dev\vcpkg\*pkgconf.exe 

Expected path:

C:\dev\vcpkg\installed\x64-windows\tools\pkgconf\pkgconf.exe 

Current CMake uses pkg-config/pkgconf for libssh discovery. A future CMake polish may prefer find_package(libssh CONFIG REQUIRED) on Windows, but the documented working setup uses pkgconf.

---

4. Clone DD-SSH

cd C:\dev git clone 
https://github.com/dklobucaric/DD-SSH.git cd C:\dev\DD-SSH 

For Windows experiments:

git checkout 
feature/windows-build 

For testing the main development line:

git fetch origin git checkout -b dev origin/dev 

---

5. Debug build

Clean old build folder:

cd C:\dev\DD-SSH rmdir /s /q build-win 

Configure:

cmake -S . -B build-win -G Ninja ^
  -DCMAKE_BUILD_TYPE=Debug ^ -DCMAKE_PREFIX_PATH=C:\Qt\6.11.1\msvc2022_64 ^ 
  -DCMAKE_TOOLCHAIN_FILE=C:\dev\vcpkg\scripts\buildsystems\vcpkg.cmake ^ 
  -DPKG_CONFIG_EXECUTABLE=C:\dev\vcpkg\installed\x64-windows\tools\pkgconf\pkgconf.exe

Build:

cmake --build build-win 

Run from the same terminal:

set 
PATH=C:\Qt\6.11.1\msvc2022_64\bin;C:\dev\vcpkg\installed\x64-windows\bin;%PATH% 
build-win\dd-ssh.exe 

---

6. Release build test

The Release build is the first meaningful performance test. Debug builds are expected to be slower and heavier.

cd C:\dev\DD-SSH rmdir /s 
/q build-win-release cmake -S . -B build-win-release -G Ninja ^
  -DCMAKE_BUILD_TYPE=Release ^ -DCMAKE_PREFIX_PATH=C:\Qt\6.11.1\msvc2022_64 ^ 
  -DCMAKE_TOOLCHAIN_FILE=C:\dev\vcpkg\scripts\buildsystems\vcpkg.cmake ^ 
  -DPKG_CONFIG_EXECUTABLE=C:\dev\vcpkg\installed\x64-windows\tools\pkgconf\pkgconf.exe
cmake --build build-win-release 

Run:

set 
PATH=C:\Qt\6.11.1\msvc2022_64\bin;C:\dev\vcpkg\installed\x64-windows\bin;%PATH% 
build-win-release\dd-ssh.exe 

Measure and record:

- app cold start time - first xterm.js terminal open time - 
second xterm.js terminal open time - RAM after Welcome screen only - RAM after one 
xterm terminal - RAM after htop is running 

Suggested notes format:

Build type: Release Windows version: Qt 
version: CPU/RAM: Welcome startup: First terminal open: Second terminal open: RAM 
Welcome: RAM with terminal: Notes: 

---

7. First runtime tests on Windows

Before testing SSH, verify UI basics:

Help → About DD-SSH Tools → Settings File → Open Config Folder 
File → Export Config 

Expected config path style:

C:\Users\<user>\AppData\Local\DD-LAB\DD-SSH\dd-ssh.json 

Then test SSH:

Session → New 
Session 

Suggested first test:

password auth → save session → double-click saved session → 
xterm.js terminal opens 

Terminal commands:

whoami hostname stty size htop exit 

Also test:

Disconnect Reconnect Settings → App theme 
System/Light/Dark Settings → font size applies to newly opened terminals 

---

8. Expected warnings and known quirks

WrapVulkanHeaders warning

CMake may print:

Could NOT find WrapVulkanHeaders (missing: Vulkan_INCLUDE_DIR) 

If configure still reaches:

Configuring done Generating done 

then this warning is currently non-fatal for DD-SSH.

First terminal startup delay

The first xterm terminal on Windows may take several seconds because Qt WebEngine initializes Chromium/WebEngine resources lazily. Later terminal tabs are much faster.

Future polish may add:

- clearer 
“Starting terminal engine...” message - optional WebEngine preload setting 

RAM usage

Qt WebEngine embeds a Chromium-based engine. With one active xterm/WebEngine terminal, RAM usage can be hundreds of MB. This is expected for the current terminal architecture and should be documented for public alpha testers.

Qt cache folder

Qt may create cache folders under:

C:\Users\<user>\AppData\Local\DD-LAB\DD-SSH\cache\ 

This is runtime/cache data, not DD-SSH session/secrets config.

---

9. Deployment handoff

This guide validates building and running from the Windows build environment. Standalone deploy-folder testing is tracked separately in docs/WINDOWS_DEPLOYMENT.md.

Current deployment checkpoint:

dev 0.1.5.7 — Known-host multi-key 
portability polish dev 0.1.5.8 — Windows libssh handshake compatibility polish dev 
0.1.5.9 — Stabilization docs and release polish 

That checkpoint covers windeployqt, copying vcpkg DLLs, running without manually extending PATH, and copying the finished dist\windows-release folder to a clean Windows 10 machine.

---

10. Current Windows build checklist

[ ] cl 
works in x64 Native Tools prompt [ ] Qt MSVC path exists [ ] Qt WebEngine exists [ ] 
Qt WebChannel exists [ ] Qt Positioning exists [ ] vcpkg libssh installed [ ] vcpkg 
pkgconf installed [ ] CMake Debug configure passes [ ] CMake Debug build passes [ ] 
app launches [ ] About shows expected version [ ] Settings opens [ ] config path is 
AppData/Local/DD-LAB/DD-SSH [ ] password SSH connection works [ ] xterm terminal 
opens [ ] htop works [x] Release configure passes [x] Release build passes [ ] 
startup/RAM notes recorded [x] Windows deploy-folder tested on Windows 10/11 [x] 
Windows libssh KEX compatibility regression validated 

Windows icon resource

From dev 0.1.5.2, DD-SSH includes a Windows .rc file and multi-size .ico generated from the project icon:

resources/windows/dd-ssh.rc 
resources/windows/dd-ssh.ico 

CMake includes the .rc file only on Windows, so the built .exe should use the DD-SSH icon instead of the default generic executable icon.

WebEngine startup note

dev 0.1.5.3 adds a clearer startup message inside new xterm.js terminal tabs. On Windows, the first terminal tab may take several seconds while Qt WebEngine initializes its Chromium-based runtime, JavaScript engine, WebChannel bridge, and graphics pipeline. This is expected for the current architecture. Later terminal tabs usually open much faster because the WebEngine runtime is already warm.

For public-alpha testing, record:

App startup time: First terminal tab startup time: Second 
terminal tab startup time: Task Manager RAM after app launch: Task Manager RAM after 
first terminal: 

This is not currently treated as a release blocker unless the terminal fails to load, the app remains permanently not responding, or subsequent tabs remain slow after the first WebEngine initialization.

---

Windows standalone deployment test

dev 0.1.5.9 documents the successful standalone Windows deployment flow, the known-host multi-key portability fix, and the Windows-only libssh KEX compatibility override for newer OpenSSH servers.

See:

docs/WINDOWS_DEPLOYMENT.md 
scripts/windows-deploy-release.bat 

The standalone deployment test uses windeployqt, copies vcpkg runtime DLLs, and creates:

dist\windows-release\ 

The goal is to run dd-ssh.exe from that folder without manually adding Qt or vcpkg paths to PATH.

Windows Standalone Deployment Test

Checkpoint: dev 0.1.5.9 — Andromeda
Purpose: document the validated standalone Windows deployment folder that can run outside the build tree and without manually extending PATH.

This is still not a final installer. It is a portable release-folder test for the Andromeda public-alpha line. The goal is to prove that a Windows-built DD-SSH can be copied into one folder with the required Qt, Qt WebEngine, libssh, OpenSSL, compiler runtime, and helper DLLs.

---

Deployment goal

Starting point:

C:\dev\DD-SSH\build-win-release\dd-ssh.exe 

Target folder:

C:\dev\DD-SSH\dist\windows-release\ 

Expected result:

dist\windows-release\dd-ssh.exe 

can be launched directly from Explorer or from a new normal Command Prompt without setting:

PATH=C:\Qt\...;C:\dev\vcpkg\... 

The final proof is copying the whole dist\windows-release folder to a clean Windows 10 machine with no Qt/vcpkg/MSVC development environment and launching dd-ssh.exe there.

---

Required paths used in the validated Windows environment

Qt: 
C:\Qt\6.11.1\msvc2022_64 vcpkg: C:\dev\vcpkg build: C:\dev\DD-SSH\build-win-release 
output: C:\dev\DD-SSH\dist\windows-release 

The helper script allows overriding these values:

set 
QT_DIR=C:\Qt\6.11.1\msvc2022_64 set VCPKG_ROOT=C:\dev\vcpkg set 
BUILD_DIR=build-win-release set DIST_DIR=dist\windows-release 

---

1. Build Release first

From x64 Native Tools Command Prompt for VS 2022:

cd C:\dev\DD-SSH rmdir /s /q 
build-win-release cmake -S . -B build-win-release -G Ninja ^
  -DCMAKE_BUILD_TYPE=Release ^ -DCMAKE_PREFIX_PATH=C:\Qt\6.11.1\msvc2022_64 ^ 
  -DCMAKE_TOOLCHAIN_FILE=C:\dev\vcpkg\scripts\buildsystems\vcpkg.cmake ^ 
  -DPKG_CONFIG_EXECUTABLE=C:\dev\vcpkg\installed\x64-windows\tools\pkgconf\pkgconf.exe
cmake --build build-win-release 

Verify that this file exists:

build-win-release\dd-ssh.exe 

The dev machine may still need Qt/vcpkg paths to run directly from the build tree. The deployment folder test below should remove that requirement.

---

2. Run the deployment helper

From the repo root:

scripts\windows-deploy-release.bat 

The script does this:

1. removes and recreates 
dist\windows-release 2. copies dd-ssh.exe 3. runs windeployqt with --release 4. 
copies vcpkg runtime DLLs from C:\dev\vcpkg\installed\x64-windows\bin 5. verifies the 
deployed executable exists 6. starts the deployed app from dist\windows-release 

The checked-in BAT is intentionally simple because that version was validated during the Windows standalone deployment test. It copies all vcpkg runtime DLLs from the vcpkg runtime bin folder. Later packaging can reduce this to the exact required DLL set. Avoid reintroducing complex batch blocks unless the change is tested on Windows 10 and Windows 11.

---

3. Manual deployment command

If the helper script is not used:

cd 
C:\dev\DD-SSH rmdir /s /q dist\windows-release mkdir dist\windows-release copy 
build-win-release\dd-ssh.exe dist\windows-release\ 
C:\Qt\6.11.1\msvc2022_64\bin\windeployqt.exe --release 
dist\windows-release\dd-ssh.exe copy C:\dev\vcpkg\installed\x64-windows\bin\*.dll 
dist\windows-release\ 

---

4. Local no-PATH test

Open a new normal Command Prompt, not the VS developer prompt.

Do not manually add Qt or vcpkg to PATH.

Run:

cd /d "C:\dev\DD-SSH\dist\windows-release" dd-ssh.exe 

Expected:

- DD-SSH opens - Help 
→ About shows dev 0.1.5.9 - app icon appears - Settings opens - config path points to 
AppData\Local\DD-LAB\DD-SSH - double-click saved session opens xterm.js terminal 

If a DLL is missing, Windows will usually report it during startup. Add that DLL source/path to this document and the deployment script.

---

5. Clean Windows 10 machine test

Copy the whole folder:

dist\windows-release 

to the clean Windows 10 test machine. Do not install Qt, vcpkg, Visual Studio Build Tools, or Ninja on that machine for this test.

Run:

dd-ssh.exe 

Minimum test pass:

[ ] app 
launches [ ] Help → About opens and shows dev 0.1.5.9 [ ] Settings opens [ ] config 
path is under AppData\Local\DD-LAB\DD-SSH [ ] new saved password session can be 
created after successful auth [ ] saved session appears in the sidebar [ ] 
double-click saved session opens xterm.js terminal [ ] whoami works [ ] htop works [ 
] disconnect works [ ] reconnect works [ ] app icon is visible on 
window/taskbar/Explorer where applicable [ ] closing with an active SSH session asks 
before exit 

Optional extra pass:

[ ] private-key auth works [ ] config export works [ ] config 
import works [ ] first terminal startup time recorded [ ] second terminal startup 
time recorded [ ] RAM usage after first terminal recorded 

---

6. Runtime checks from deployed folder

Use either an imported config or create a new test session.

Check:

Help → About 
DD-SSH Tools → Settings File → Open Config Folder File → Export Config Session → New 
Session Double-click saved session 

Terminal commands:

whoami hostname stty size htop exit 

Also test:

- Disconnect - Reconnect - first terminal 
loading message - second terminal opens faster than the first 

---

7. Expected deployment contents

The deployment folder will be much larger than dd-ssh.exe because Qt WebEngine includes a Chromium-based runtime.

Expected contents include some of:

dd-ssh.exe Qt6*.dll libEGL.dll / libGLESv2.dll D3D compiler / 
graphics helper DLLs QtWebEngineProcess.exe resources\ translations\ imageformats\ 
platforms\ styles\ tls\ ssh.dll or libssh.dll libcrypto*.dll libssl*.dll zlib*.dll 

Exact filenames depend on Qt and vcpkg versions.

---

8. Known Windows deployment notes

• Qt WebEngine deployment is larger than a plain Qt Widgets app.
• The first terminal tab may still take several seconds while WebEngine initializes.
• Runtime RAM use with one WebEngine terminal may be hundreds of MB.
• Qt may create cache folders under the DD-SSH AppData location.
• This deployment test does not create an installer yet.
• This deployment test is not code-signed.
• If the clean machine reports a missing DLL, add that DLL to the deployment script notes before calling the checkpoint passed.
• If a modern OpenSSH server fails only on Windows with Failed to construct client init buffer, review docs/WINDOWS_LIBSSH_HANDSHAKE_COMPATIBILITY.md. The dev 0.1.5.8+ Windows KEX compatibility override should handle the validated regression case.

---

9. Pass criteria for Windows deployment

Mark this checkpoint as passed when:

[x] Release build succeeds [x] 
deployment folder is created [x] app starts from deployment folder without Qt/vcpkg 
PATH [x] About shows dev 0.1.5.9 [x] app icon appears in Explorer/taskbar/window [x] 
Settings opens and saves [x] xterm terminal opens [x] SSH password login works [x] 
whoami works [x] htop works [x] Disconnect/Reconnect still work [x] clean Windows 10 
machine launches dd-ssh.exe from copied folder 

DD-SSH Windows libssh Handshake Compatibility Test

Checkpoint: dev 0.1.5.9 — Andromeda
Focus: Windows libssh KEX compatibility with newer OpenSSH servers

Real regression case

Problematic connection:

Host: 
lab.dd-lab.hr Port: 2231 Forwarded target: 192.168.1.233:223 Server banner: 
OpenSSH_10.0p2 Debian-7+deb13u2 

Observed before dev 0.1.5.8:

Linux DD-SSH: works Windows OpenSSH: works and 
reaches authentication Windows DD-SSH dev build: fails during handshake Windows 
DD-SSH standalone build: fails during handshake DD-SSH error: Failed to construct 
client init buffer 

The same Windows failure occurred through the public port forward, through VPN, and through the local network path. This ruled out DNS and port forwarding as the primary cause.

Why this happens

The server advertises modern OpenSSH key-exchange algorithms first, including:

mlkem768x25519-sha256 sntrup761x25519-sha512 
sntrup761x25519-sha512@openssh.com curve25519-sha256 curve25519-sha256@libssh.org 

Windows OpenSSH successfully negotiated:

kex: algorithm: curve25519-sha256 kex: host key algorithm: 
ssh-ed25519 

Windows libssh/vcpkg failed before authentication with:

Failed to construct client init buffer 

dev 0.1.5.8+ behavior

On Windows builds only, DD-SSH sets a conservative KEX list before ssh_connect():

curve25519-sha256, curve25519-sha256@libssh.org, 
ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, 
diffie-hellman-group14-sha256 

This applies to:

• Manual handshake tests
• Authentication tests
• Real shell sessions

Linux and future macOS builds do not apply this Windows-only override.

Validation result

Current validated result as of dev 0.1.5.9 docs:

Windows 10 DD-SSH: PASS Windows 11 DD-SSH: PASS 
Linux DD-SSH: PASS Server-side KEX workaround: no longer required for this DD-SSH 
regression case 

Diagnostic switches

Enable libssh protocol verbosity locally:

set DD_SSH_LIBSSH_DEBUG=1 
dist\windows-release\dd-ssh.exe 

Disable the Windows KEX compatibility override for comparison testing:

set DD_SSH_DISABLE_WINDOWS_KEX_COMPAT=1 
dist\windows-release\dd-ssh.exe 

Do not ship normal user runs with these variables set unless debugging.

Expected test

1. Build DD-SSH dev 0.1.5.9 on Windows.
2. Deploy with scripts\windows-deploy-release.bat.
3. Open the problematic saved session to lab.dd-lab.hr:2231.
4. Expected result: handshake succeeds and DD-SSH reaches known-host/auth/shell flow.
5. Optional comparison: set DD_SSH_DISABLE_WINDOWS_KEX_COMPAT=1; the old failure may return on affected Windows/libssh builds.

Server-side workaround used to prove the bug

This temporary server config made Windows DD-SSH work before the app-side fix:

KexAlgorithms 
curve25519-sha256,curve25519-sha256@libssh.org,ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group14-sha256 

Validated after dev 0.1.5.8 on two Windows machines and one Linux machine: the server-side compatibility file is no longer needed for DD-SSH in this regression case.

DD-SSH Linux packaging assets

This directory contains early Linux packaging helpers.

The first Debian package experiment is intentionally simple:

• build from the local CMake Release tree
• install the binary, desktop launcher, icons, and documentation under /usr
• generate a .deb with dpkg-deb
• use distro Qt/libssh runtime packages instead of bundling Qt libraries

See docs/LINUX_PACKAGING.md.

AGENTS.md

Guidelines for AI coding agents working on DD-SSH.

Project

DD-SSH is a cross-platform SSH client and session manager.

Current checkpoint:

Version: dev 0.1.6.1.1 Codename: Andromeda 
Milestone: MF 0.2 candidate Phase: README screenshots and Debian packaging tutorial 
polish 

Stack

• C++20
• Qt 6
• CMake
• libssh
• Qt WebEngine + Qt WebChannel
• local bundled xterm.js assets
• JSON config

Hard rules

• Do not add Electron.
• Do not add telemetry.
• Do not store secrets in logs.
• Do not print password/private-key values.
• Do not hardcode Linux-only paths without abstraction.
• Use Qt standard paths for config locations.
• Do not silently accept changed host keys.
• Do not overwrite corrupt config files automatically.
• Do not change config format without updating docs/CONFIG_FORMAT.md.
• Do not add SFTP or split panes into early scope unless explicitly requested.
• Keep Windows/macOS portability in mind even when developing on Linux.

Current config warning

DD-SSH currently stores secrets in plaintext under:

secrets.mode = plain-v1 

Treat all real dd-ssh.json files and backups as sensitive.

Versioning rule

Every generated checkpoint must update:

CMakeLists.txt → DD_SSH_VERSION_STRING 

If appropriate, also update:

README.md 
docs/CHANGELOG.md docs/TEST_MATRIX.md Welcome/About phase text 

Architecture rule

Prefer focused classes.

Do not dump everything into MainWindow.

Current important classes:

• MainWindow
• ConnectDialog
• SettingsDialog
• WebTerminalTab
• TerminalBridge
• ConfigManager
• KnownHostsManager
• SshSession
• SshShellWorker

Testing rule

Before declaring a terminal checkpoint healthy, manually test at least:

whoami hostname stty size htop nano /tmp/dd-ssh-test.txt vim 
/tmp/dd-ssh-test.txt clear exit 

For lifecycle changes, also test remote reboot/disconnect and reconnect.

Public alpha documentation

When changing user-facing behavior during the Andromeda alpha line, update the relevant docs:

• README.md
• docs/CHANGELOG.md
• docs/TEST_MATRIX.md
• docs/SECURITY_NOTES.md if secrets/config behavior changes
• docs/CONFIG_FORMAT.md if JSON structure changes
• docs/PUBLIC_ALPHA_CHECKLIST.md if release validation changes

Do not mark a test as PASS unless it was actually confirmed.

Packaging rule

When changing Linux/Windows/macOS packaging behavior, update docs/PACKAGING.md, docs/LINUX_PACKAGING.md or the relevant platform packaging guide, and docs/CHANGELOG.md. Do not package real user configs or secrets.