User-facing documentation (guides, FAQ) lives on the wiki. This folder holds developer and platform documentation that versions with the code:
| Document | Contents |
|---|---|
| architecture.md | How the app is put together: the single SSH connection/auth path, secret backends, askpass mechanics, platform notes and debugging. Read this before changing how the app connects. |
| running-from-source.md | Running from source on Linux: the hybrid (system PyGObject + venv) and pure-venv (pip-built PyGObject) approaches, plus dev/test setup and troubleshooting. |
| INSTALL-macos.md | Installing and running from source on macOS (Homebrew GTK stack). |
| keyboard-shortcuts.md | Full shortcut reference for Linux and macOS. |
| diagnostics.md | Where the logs live, the crash report, the --diagnostics flags and the bug-report bundle. |
| agent-architecture.md | The Ptyxis-style agent that provides host shells with job control under Flatpak. |
| SSH-config-parsing.md | Design rationale for host discovery: display-only parsing, ssh -G as the source of truth. |
| command-converter.md | The ssh ... command-line → connection-data parser (used by CLI connect and available for paste/import). |
| PLUGIN_SDK.md | The plugin API reference: context objects, protocol backends, UI pages, credential dialogs. |
| IDENTITY_PROVIDERS.md | The identity-provider contract (which key authenticates a connection, and who supplies it). |
| CREDENTIAL_MANAGER.md | The credential export/backup layer and its secret backends. |
| plugins/ | Writing, packaging and publishing plugins, plus copyable templates. |
The askpass helper doesn't log through the main logger. It writes debug
information to sshpilot-askpass.log in the first available of:
$SSHPILOT_ASKPASS_LOG_DIR, if set$XDG_RUNTIME_DIR- the system temporary directory
No askpass messages appear in the normal console or application log.