⏻
HELGE SVERREAll-stack Developer
Bergen, Norway • v13.0
est. 2012  |  197 repos  |  12.8k+ contributions
Tools  |   Theme:
Fix 'xterm-ghostty' Unknown Terminal Type When SSHing
October 23, 2026

The Problem

When SSHing into remote servers from Ghostty, you may see:

'xterm-ghostty': unknown terminal type.

Ghostty sets its TERM value to xterm-ghostty, but remote servers do not include this terminfo entry.

Quick Fix

Add this to your Ghostty config (~/.config/ghostty/config.ghostty):

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

That's it. Ghostty will automatically transfer the terminfo entry when you SSH to remote servers, and fall back to xterm-256color when it can't. This needs Ghostty 1.2.0 or newer.

What the Two Flags Do

  • ssh-env sets TERM=xterm-256color for the session and forwards COLORTERM, TERM_PROGRAM and TERM_PROGRAM_VERSION (the remote sshd_config has to accept them).
  • ssh-terminfo installs Ghostty's terminfo on the remote with infocmp/tic and caches which hosts already have it. ghostty +ssh-cache lists the cache.

With both on, Ghostty tries to install terminfo and keep xterm-ghostty. It falls back to xterm-256color if the install fails.

SSH integration landed in PR #7608 and shipped in Ghostty 1.2.0 on 2025-09-15. It started out as a separate option, ssh-integration = basic | full. Mitchell asked for opt-in features inside the existing shell-integration-features list instead, which is why it's two independent flags rather than a level.

Run ghostty +validate-config after editing to catch invalid values.

Coming Next: ghostty +ssh

PR #12582 (merged May 2026) adds a ghostty +ssh action. It replaces the per-shell SSH wrapper code with one native command, and you can alias it with alias ssh='ghostty +ssh --'. It isn't in 1.3.1, the latest release. It's only in tip builds.

Manual Alternatives

If you prefer manual setup:

Copy terminfo to remote server:

infocmp -x xterm-ghostty | ssh user@host -- tic -x -

SSH fallback to xterm-256color:

# ~/.ssh/config
Host your-server
    SetEnv TERM=xterm-256color

Verification

Check terminfo is installed:

infocmp xterm-ghostty

Shell integration provides the cleanest approach. You will not see this error again and you won't need to manage terminfo commands for new servers.




<!-- generated with nested tables and zero regrets -->