Getting Started

Getting started

First launch - vault setup

Windows, Linux and Android have release downloads. macOS has none (it would need an Apple Developer ID): there scripts/macos-build.sh builds and installs the app and the VPN plugins you pick after a few questions - see docs/macos.md.

On first launch the app shows a vault gate. The vault stores credential secrets (passwords, private keys, opkssh material) encrypted on disk with:

• Argon2id key derivation (interactive-grade parameters: m=19MiB, t=2, p=1)
• XChaCha20-Poly1305 authenticated encryption

Two paths:

• Set master passphrase (first run) - you choose the passphrase that protects the vault.
• Unlock vault (subsequent runs) - type the same passphrase.

Optional: Remember on this machine ticks the auto-unlock sidecar. The next launch skips the prompt by deriving the unlock key from a file kept under the OS keychain when available.

The vault file lives outside the SQLite DB so the encrypted secrets don't share blast radius with the connection tree.

Auto-lock: Settings → Vault → "Auto-lock after idle (minutes)" re-locks the vault and re-prompts at the VaultGate after the specified idle period. 0 (default) disables. Open terminal sessions and port forwards keep running across a lock - only the credential tree is re-protected.

Layout overview

The main window has a top tab bar with four sections:

• Connections - folder tree on the left, connection editor on the right. With nothing selected the right side shows the home pane (see §3, Home pane).
• Credentials - credential folder tree on the left, credential editor on the right.
• Settings - side-nav with grouped settings panels.
• Terminal - visible only while at least one session is open. Shows tab bar + pane tree.

On the right edge of the top tab bar:

• Native terminal button - opens a fresh local OS terminal (no SSH attached). Useful for quick local commands without leaving the app. Spawns Windows Terminal / PowerShell / cmd per Settings → Connection → External terminal on Windows; Terminal.app on macOS; $TERMINAL or a fallback list on Linux.
• Search button (Ctrl+K) - opens the quick palette.

The sidebar (left column) of Connections and Credentials views is resizable via the drag handle between sidebar and detail. Width persists across launches.

The OS window and taskbar title reflect what you're looking at: the active terminal tab's name (e.g. myhost - ssh-tool), or the section name on the Connections / Credentials / Settings views. Handy when several windows are open or you're alt-tabbing.

The window remembers its geometry across runs: size, position, which monitor (in a multi-display setup) and whether it was maximised. Relaunching reopens it where you left it.

A status bar along the bottom (22 px) surfaces, from left to right:

• Workspaces dropdown - recent workspaces + Save current as… + Manage…
• Live session count (clickable, jumps to Terminal). Coloured yellow if any are in error.
• Active tunnels indicator (green cable + count) when at least one port-forward is listening anywhere in the app. Hidden at zero.
• Broadcast indicator when a group is active (with member count).
• Focused connection name + host (Terminal view only).
• Server status readout (load / memory / disk / users) for the focused SSH session, when that optional feature is enabled in Settings. Click it for a System status popup: CPU load against core count, memory + swap, every real filesystem (pseudo/temp mounts like tmpfs and /boot/efi are hidden), uptime, kernel, and the logged-in users by name. A refresh button re-probes on demand. It reads the remote host of the focused session over a read-only side channel - the same probe the readout uses.
  • Values turn yellow, then red, near their limit (load per core, memory, disk). The disk figure is the fullest filesystem, not only /; inode use speaks up the same way when it runs out first.
  • More under a filesystem shows inode use and Find largest directories (du -x, two levels, only on click, capped at 20 s).
  • Processes tab: the top 5, 10 or 20 by CPU or memory; the row menu copies the PID or command line, or sends SIGTERM / SIGKILL after a confirmation.
  • Services tab: failed, running or all units. Open one for its last journal lines, restart / stop / start, a log tail on it, or systemctl status typed into the terminal (you press Enter).
  • Actions that need root run as the login user first, then through sudo -n, then with the connection's stored password; only if all of that fails does the app ask for a sudo password.
  • A red N failed chip appears next to the readout when a systemd unit has failed; it opens the Services tab. A failed unit there has Ignore on this host or one of its folders (a folder covers every host below it, dynamic inventory hosts too): it stays listed (greyed, "ignored") but stops counting toward the chip. Warn about failed systemd units in Settings turns the chip off everywhere.
  • Local shells show the machine they run on: WSL its distro, PowerShell / cmd read Windows (CPU as a busy percentage), Linux and macOS the machine itself. WSL and Linux shells also get read-only Processes and Services tabs (no kill / restart; ignore per distro).
• Update-available pill when a newer release is published. Settings -> Updates -> Channel: Stable (default) offers releases only; Release candidates also offers the test builds of the next release (vX.Y.Z-rcN), with that release's changelog in the update dialog, and moves on to the release itself when it ships. Leaving the channel keeps an installed candidate until a release overtakes it - there is no downgrade.
• A log tail segment shows while any log tail runs (open, minimised or in its own window), the way captures do: click it to open the tail, or pick one when several run.
• Right-click the status bar to pick which items it shows; warnings (locked vault, issues, updates, sharing, VPN) always show.
• Version pill on the right - click to jump to Settings → About.

Toast notifications appear in the bottom-right corner for non-blocking confirmations (saves, errors). Click a toast to dismiss early, otherwise they auto-dismiss after a couple of seconds.