====== Installing Saltbush Terminal ======

Get version 1.8.2 from [[https://retro.theiguru.au/saltbush/|the download page]]. Both platforms are 64-bit.

===== Windows =====

Download ''saltbush-1.8.2-windows-x64-setup.exe'' and run it. It installs for your own user (no administrator rights) under ''%LOCALAPPDATA%\Programs\Saltbush Terminal'' and adds **Saltbush Terminal** to the Start menu. Remove it from **Settings → Apps** or with the Uninstall shortcut; your settings are kept.

For a portable copy, extract ''saltbush-1.8.2-windows-x64.zip'' anywhere and run ''Saltbush Terminal\saltbush.exe''. Keep the DLL files next to it.

  * Settings are kept in ''%APPDATA%\saltbush''.
  * Credential passwords go into Windows Credential Manager.
  * Python scripts need Python 3 from python.org with ''python'' on the PATH. Lua is built in.
  * The OpenSSH engine and SFTP sessions use Windows' own ''ssh.exe'' and ''sftp.exe''.
  * Serial ports are the COM ports Windows lists.
  * For Tools → SSH Agent, start the "OpenSSH Authentication Agent" service (Services, set it to Manual or Automatic and start it).

The Windows version has been tested under Wine. Tell us if something does not work on your PC.

===== Linux (Debian, Ubuntu, Mint) =====

Download ''saltbush_1.8.2_amd64.deb'', open a terminal in that folder and run:

<code bash>
sudo apt install ./saltbush_1.8.2_amd64.deb
saltbush
</code>

It needs Ubuntu 24.04, Debian 13 or newer. apt installs libssh and the other libraries, and suggests ''libsecret-tools'' (credential passwords) and ''python3''. After installing, Saltbush Terminal also shows up in Discover and other software centres. Remove it with ''sudo apt remove saltbush''.

===== Linux (any distribution) =====

<code bash>
tar xf saltbush-1.8.2-linux-x86_64.tar.gz
cd saltbush-1.8.2-linux-x86_64
./install.sh
</code>

This installs into ''~/.local'' without root. ''./install.sh --uninstall'' removes it again. It needs glibc 2.34 or later and libssh (''libssh-4'' or your distribution's equivalent).

Settings are kept in ''~/.config/saltbush'' (''SALTBUSH_CONFIG'' chooses another folder). The file is written safely and readable only by you; if it ever cannot be read it is kept as ''settings.json.bad-<date>'' rather than overwritten.

===== Updates =====

From version 1.5.0, Saltbush Terminal tells you when a new version is out. Once a day, a few seconds after it starts, it reads a small file on the website (''https://retro.theiguru.au/saltbush/latest.json'') that names the newest version. Nothing about you is sent, only the Saltbush version and operating system.

When there is a newer version, a window shows what is new, with three buttons:

  * **Update Now** downloads the new version, checks it against its published checksum and installs it:
    * Debian package: it installs the new ''.deb'' and asks for your password (the normal system password prompt). Then choose **Restart Now**, or keep working and restart later.
    * Windows installer: the new setup program starts and Saltbush Terminal closes so the files can be replaced. Follow the installer and start Saltbush again.
    * Portable ZIP, tar archive or your own build: the download page opens so you can fetch the new files yourself.
  * **Not Now** closes the window. You are asked again at the next daily check.
  * **Skip This Version** stops notices about that version. You will still hear about the next one.

**Help → Check for Updates…** checks straight away, even for a skipped version, and tells you if you already have the latest. To stop the daily check, untick **Tell me when a new version is available** in the update window or in **Options → Global Options**.

Version 1.4.0 and older have no update check: install 1.5.0 by hand once, the same way as a new install (on Linux, ''sudo apt install ./saltbush_1.5.0_amd64.deb'' upgrades in place and keeps your settings). Updating needs ''curl'', which Windows 10 and later and most Linux systems include.

===== Troubleshooting =====

  * **SSH asks about the host key every time:** the session's **Known hosts file** (Session Options → SSH2) must be writable.
  * **A session says it uses the OpenSSH client:** it needs a feature the built-in engine does not have (a jump host, an Ed25519 certificate, extra ''-o'' options, or agent forwarding on Windows). Install the OpenSSH client.
  * **Serial port will not open on Linux:** add yourself to the ''dialout'' group and log in again.
  * **Paste does nothing on Linux (1.4.0 and older):** on Wayland desktops such as KDE Plasma only Ctrl+Shift+V pasted. Update to 1.5.0, where every way of pasting works.
  * **Plain Ctrl+V does not paste:** by default Ctrl+C and Ctrl+V go to the program in the terminal. Use Ctrl+Shift+C and Ctrl+Shift+V, or turn on the copy and paste keys in **Session Options → Input**.
  * **"Could not check for a new version":** the computer could not reach the website, or ''curl'' is missing. **Open Download Page** in that window still works.
  * **Update Now on Linux says it was cancelled:** the password prompt was closed. Try again, or install the downloaded package from ''~/.cache/saltbush/updates'' with ''sudo apt install''.
  * **Python script does not start:** install Python 3; on Windows tick "Add python.exe to PATH" in its installer.