Skip to main content

Kitty SSH Basics

Kitty provides native SSH integration that goes beyond a standard terminal. When you SSH using kitty +kitten ssh, you get automatic terminfo installation, inline image support, and access to kitty kittens on the remote host.

Learning Focus

Always use kitty +kitten ssh instead of the standard ssh command. It handles terminfo forwarding automatically and gives you the full kitty feature set on remote servers.

Why Kitty SSH Matters​

Standard SSH sessions treat the remote terminal as a dumb terminal. Kitty extends this with:

FeatureStandard sshkitty +kitten ssh
Terminfo forwarding❌ Manually✅ Automatic
Inline images (icat)❌✅
Clipboard protocol❌✅ (with config)
Kitty kittens remotely❌✅ (remote_file, etc.)
True color supportManual TERM setting✅ Automatic
Font ligatures❌✅
Scrollback integrationBasic✅ Full kitty scrollback

Architecture: Regular SSH vs Kitty SSH​

Regular SSH:
┌──────────┐     SSH      ┌──────────────────┐
│ Terminal │─────────────▶│  Remote Server    │
│ (dumb)   │              │  TERM=xterm-256   │
└──────────┘              │  No image support │
                          │  No kitty kittens │
                          └──────────────────┘

Kitty SSH (+kitten):
┌──────────┐  SSH + terminfo  ┌──────────────────┐
│ Kitty    │─────────────────▶│  Remote Server    │
│ (local)  │   forwarding     │  TERM=xterm-kitty  │
│          │                  │  icat works ✅    │
│          │                  │  kittens work ✅  │
└──────────┘                  │  clipboard ✅     │
                              └──────────────────┘

Using kitty +kitten ssh​

# Standard usage — just replace ssh with kitty +kitten ssh
kitty +kitten ssh user@server.example.com

# Specify a port
kitty +kitten ssh -p 2222 user@server.example.com

# With additional SSH options
kitty +kitten ssh -o "ServerAliveInterval 60" user@server.example.com

# Proxy jump
kitty +kitten ssh -J jumpbox.example.com user@internal-server
info

kitty +kitten ssh passes through all standard SSH options (-p, -i, -J, -o, etc.) to the underlying ssh command. Your ~/.ssh/config is fully respected.

What Happens When You Connect​

1. You run: kitty +kitten ssh user@server

2. Kitty checks if remote has xterm-kitty terminfo
   ├── If YES → connect normally
   └── If NO  → offer to install terminfo automatically

3. Kitty sets TERM=xterm-kitty on the remote

4. Remote applications detect kitty capabilities:
   ├── True color support
   ├── Inline image protocol
   ├── Clipboard OSC 52
   └── Kitty protocol extensions

The Remote File Kitten​

The remote_file kitten lets you open remote files in local editors:

# Edit a remote file in your local vim
kitty +kitten remote_file user@server:/var/log/syslog

# Read remote file to stdout
kitty +kitten remote_file --stdout user@server:/etc/nginx/nginx.conf

# Copy remote file to local
kitty +kitten remote_file --stdout user@server:/etc/hosts > /tmp/remote-hosts
note

The remote_file kitten uses SCP under the hood. It authenticates via the same SSH keys and ~/.ssh/config you normally use.

Persistent Remote Sessions (with tmux)​

Kitty is a terminal emulator, not a session multiplexer. For persistent sessions on remote servers, pair kitty with tmux:

# Connect to remote with kitty SSH, then start tmux
kitty +kitten ssh user@server
tmux new -s remote-work

# Or one-liner
kitty +kitten ssh -t user@server "tmux new -s remote-work || tmux attach -t remote-work"

Opening a Local Shell in the Remote CWD​

When you SSH into a server using kitty, you can open a local window or tab that starts in the same directory as the remote session. This is useful for parallel local work:

# Inside a remote SSH session, run:
kitty @ launch --type=window --cwd "$(pwd)"

This tells the local kitty instance to create a window in the same directory — handy when you need to compare local and remote files.

Common Pitfalls​

PitfallSymptomFix
Forgot +kitten in kitty +kitten sshStandard SSH with no kitty featuresAlways use the full kitty +kitten ssh syntax
Remote server lacks infocmpTerminfo check failsInstall ncurses-bin on remote (or use --install-terminal)
Attempting session persistence with kittyProcesses killed on disconnectUse tmux inside the remote SSH session for persistence
SSH config not respectedConnection uses wrong keykitty +kitten ssh passes through ~/.ssh/config normally
TERM=xterm-kitty not set remotelyMissing kitty featuresVerify with echo $TERM after connecting

Hands-On Practice​

# 1) Basic kitty SSH connection (replace with your server)
# kitty +kitten ssh user@your-server

# 2) Test that terminfo is working (once connected)
echo $TERM
# Should output: xterm-kitty

# 3) Test true color (should show smooth gradient)
awk 'BEGIN{
  for(i=0;i<256;i++){
    printf "\x1b[48;2;%d;%d;%dm ", i, 255-i, i;
  }
  printf "\x1b[0m\n"
}'

# 4) If you can't connect to a real server, test locally:
# Kitty SSH to localhost
kitty +kitten ssh localhost

# 5) Check available kittens on remote (if connected)
ls ~/.local/kitty*/bin/ 2>/dev/null || echo "No kittens installed on remote"

What's Next​