Ghostty 1.4 SSH: Choose the Right Fix for Terminal Errors

If Ghostty connects to your server but a terminal program complains about xterm-ghostty, start by identifying how that connection was launched. SSH provides a connection to a remote machine, but a command typed in your shell and a connection started by another tool can take different setup paths.

Ghostty 1.4.0, released on 27 October 2026, adds a ghostty +ssh command. It gives you a direct way to prepare the remote terminal environment. Here is a practical order for choosing it, checking the result and handling connections it does not automatically cover.

Check the version before changing settings

The new command is absent from Ghostty 1.3.x. The SSH documentation still has a pre-release note saying it requires the development build; the dated 1.4 release notes confirm that it has shipped. Use the installed application's version information to check which guidance applies.

On Linux, check your distribution's package version rather than assuming the new release is already installed. Ghostty's installation guide distinguishes its official macOS binaries from Linux packages maintained by distributions and the community. Also check 1.4's system requirements before upgrading: its GTK application now requires GTK 4.18 and libadwaita 1.7. The release notes identify Flatpak as an option for systems with older libraries.

Start with one explicit connection

For a server you are authorised to access and configure, replace the example destination below with your own:

ghostty +ssh -- user@example.com

According to the SSH feature documentation, the wrapper runs the real SSH client after preparing the session. It attempts to install Ghostty's terminal description, which tells programs what the terminal supports, using the remote tic utility. If installation fails, it warns and falls back to xterm-256color. This can restore compatibility without giving the remote program every Ghostty-specific capability.

To check the result, rerun the same terminal program that failed, on the same host and account. Note whether the warning disappeared and whether the keys and screen drawing you actually use behave correctly. A successful login alone does not establish that the application is fixed. This is a suggested diagnostic procedure, not a test we performed on your server.

Choose the path that matches the caller

For supported shells, Ghostty offers this opt-in configuration:

shell-integration-features = ssh-env,ssh-terminfo

If you already customise that setting, review and preserve the other features you need. The shell-integration guide lists bash, elvish, fish, Nushell and zsh, with a manual-setup caveat for macOS's bundled Bash. Simply installing Ghostty does not prove that the optional SSH wrapper is active.

The SSH documentation explicitly excludes callers such as Git, scp, sftp and rsync from the interactive shell function. For a script you control, an explicit ghostty +ssh invocation can use the wrapper. For other tools, follow their supported configuration rather than assuming your shell setting reaches them.

Keep a fallback specific to the host

Ghostty's terminfo guide explains why a remote host needs a matching terminal description. Its documented compatibility alternative, requiring OpenSSH 8.7 or newer, is a host entry in your local ~/.ssh/config file:

Host example.com
  SetEnv TERM=xterm-256color

Replace the hostname with the intended destination. Keeping this limited to one host makes the tradeoff explicit; avoid changing every connection to solve a single server's problem. Where the full terminal description is wanted, the same guide documents manual installation instead.

If an error appears only after sudo, investigate that separately: Ghostty documents that sudo can reset the environment containing the terminfo location. An SSH-only change is not evidence that this second context is repaired.

For example, if an interactive connection works but a deployment script still fails, compare their launch commands before changing the server again. If both fail on one managed machine, take the exact warning to its administrator. That distinction is more useful than applying several unrelated configuration changes at once.

Editorial disclosure: This guide was researched and edited with AI assistance against Ghostty's documentation. No live SSH, operating-system installation or performance testing was performed. The cover is an AI-generated conceptual illustration, not a Ghostty screenshot. No sponsorship, paid placement or affiliate links are included.