Truly convenient SSH#
Automatic Shell integration on remote hosts
Easily clone local shell/editor config on remote hosts
re-use of existing connectionsto avoid connection setup latency
Make kitty itself available in the remote host
change terminal colorswhen connecting to remote hosts
New in version 0.25.0: Automatic shell integration, file transfer and reuse of connections
The ssh kitten allows you to login easily to remote hosts, and automatically setup the environment there to be as comfortable as your local shell. You can specify environment variables to set on the remote host and files to copy there, making your remote experience just like your local shell. Additionally, it automatically sets up Shell integration on the remote host and copies the kitty terminfo database there.
The ssh kitten is a thin wrapper around the traditional ssh
command line program and supports all the same options and arguments and configuration.
In interactive usage scenarios it is a drop in replacement for
ssh. To try it
out, simply run:
kitty +kitten ssh some-hostname-to-connect-to
You should end up at a shell prompt on the remote host, with shell integration enabled. If you like it you can add an alias to it in your shell’s rc files:
alias s=kitty +kitten ssh
So now you can just type
s hostname to connect.
If you define a mapping in
kitty.conf such as:
map f1 new_window_with_cwd
Then, pressing F1 will open a new window automatically logged into the same host using the ssh kitten, at the same directory.
The ssh kitten can be configured using the
file where you can specify environment variables to set on the remote host
and files to copy from the local to the remote host. Let’s see a
# Copy the files and directories needed to setup some common tools copy .zshrc .vimrc .vim # Setup some environment variables env SOME_VAR=x # COPIED_VAR will have the same value on the remote host as it does locally env COPIED_VAR=_kitty_copy_env_var_ # Create some per hostname settings hostname someserver-* copy env-files env SOMETHING=else hostname someuser@somehost copy --dest=foo/bar some-file copy --glob some/files.*
See below for full details on the syntax and options of
Additionally, you can pass config options on the command line:
kitty +kitten ssh --kitten interpreter=python servername
--kitten argument can be specified multiple times, with directives
ssh.conf. These are merged with
ssh.conf as if they were
appended to the end of that file. They apply only to the host being SSHed to
by this invocation, so any
hostname directives are ignored.
Due to limitations in the design of SSH, any typing you do before the shell prompt appears may be lost. So ideally don’t start typing till you see the shell prompt. 😇
A real world example#
Suppose you often SSH into a production server, and you would like to setup your shell and editor there using your custom settings. However, other people could SSH in as well and you don’t want to clobber their settings. Here is how this could be achieved using the ssh kitten with zsh and vim as the shell and editor, respectively:
# Have these settings apply to servers in my organization hostname myserver-* # Setup zsh to read its files from my-conf/zsh env ZDOTDIR $HOME/my-conf/zsh copy --dest my-conf/zsh/.zshrc .zshrc copy --dest my-conf/zsh/.zshenv .zshenv # If you use other zsh init files add them in a similar manner # Setup vim to read its config from my-conf/vim env VIMINIT $HOME/my-conf/vim/vimrc env VIMRUNTIME $HOME/my-conf/vim copy --dest my-conf/vim .vim copy --dest my-conf/vim/vimrc .vimrc
How it works#
The ssh kitten works by having SSH transmit and execute a POSIX sh (or
optionally Python) bootstrap script on the
remote host using an
interpreter. This script
reads setup data over the tty device, which kitty sends as a base64 encoded
compressed tarball. The script extracts it and places the
and sets the
environment variables before finally
login shell with
integration enabled. The data is requested by
the kitten over the TTY with a random one time password. kitty reads the request
and if the password matches a password pre-stored in shared memory on the
localhost by the kitten, the transmission is allowed. If your OpenSSH version is
>= 8.4 then the data is transmitted instantly without any roundtrip delay.
When connecting to BSD hosts, it is possible the bootstrap script will
fail or run slowly, because the default shells are crippled in various ways.
Your best bet is to install Python on the remote, make sure the login shell
is something POSIX sh compliant, and use
python as the
Host bootstrap configuration#
The hostname that the following options apply to. A glob pattern to match multiple
hosts can be used. Multiple hostnames can also be specified separated by spaces.
The hostname can include an optional username in the form
When not specified options apply to all hosts, until the
first hostname specification is found. Note that matching of hostname is done against
the name you specify on the command line to connect to the remote host.
If you wish to include the same basic configuration for many
different hosts, you can do so with the include directive.
The interpreter to use on the remote host. Must be either a POSIX complaint shell or a python executable. If the default sh is not available or broken, using an alternate interpreter can be useful.
The location on the remote host where the files needed for this kitten are installed. The location is relative to the HOME directory. Absolute paths or paths that resolve to a location outside the HOME are not allowed.
Copy files and directories from local to remote hosts. The specified files are assumed to be relative to the HOME directory and copied to the HOME on the remote. Directories are copied recursively. If absolute paths are used, they are copied as is. For example:
copy .vimrc .zshrc .config/some-dir
If a file should be copied to some other destination on the remote host,
copy --dest some-other-name some-file
Glob patterns can be specified to copy multiple files, with
copy --glob images/*.png
Files can be excluded when copying with
copy --glob --exclude *.jpg --exclude *.bmp images/*
Files whose remote name matches the exclude pattern will not be copied. For more details, see The copy command.
Login shell environment#
Control the shell integration on the remote host. See Shell integration
for details on how this setting works. The special value
use the setting from
kitty.conf. This setting is useful for overriding
integration on a per-host basis.
The login shell to execute on the remote host. By default, the remote user account’s login shell is used.
Specify environment variables to set on the remote host. Note that environment variables can refer to each other, so if you use:
env MYVAR1=a env MYVAR2=$MYVAR1/$HOME/b
The value of MYVAR2 will be
a/<path to home directory>/b. Using
VAR= will set it to the empty string and using just
will delete the variable from the child process’ environment. The definitions
are processed alphabetically. The special value
will cause the value of the variable to be copied from the local environment.
The working directory on the remote host to change to. Env vars in this value are expanded. The default is empty so no changing is done, which usually means the home directory is used.
Specify a color scheme to use when connecting to the remote host. If the
color_scheme ends with
.conf it is assumed to be the name of a config
file to load from the kitty config directory, otherwise it is assumed to be the
name of a color theme to load via the themes kitten. Note that only colors
applying to the text/background are changed, other config settings in the .conf
files/themes are ignored.
Make kitty available on the remote server. Useful to run kittens such as the
icat kitten to display images or the transfer file kitten to transfer files.
Only works if the remote server has an architecture for which pre-compiled
kitty binaries are available. Note that kitty is not actually copied to the
remote server, instead a small bootstrap script is copied which will download
and run kitty when kitty is first executed on the remote server. A value of
if-needed means kitty is installed only if not already present in the
system-wide PATH. A value of
yes means that kitty is installed even if
already present, and the installed kitty takes precedence. Finally,
means no kitty is installed on the remote machine. The installed kitty
can be updated by running:
kitty +update-kitty on the remote machine.
Within a single kitty instance, all connections to a particular server can be shared. This reduces startup latency for subsequent connections and means that you have to enter the password only once. Under the hood, it uses SSH ControlMasters and these are automatically cleaned up by kitty when it quits.
Control the program SSH uses to ask for passwords or confirmation of host keys
etc. The default is to use kitty’s native askpass, unless the SSH_ASKPASS
environment variable is set. Set it to
ssh to not interfere with the
normal ssh askpass mechanism at all, which typically means that ssh will prompt
at the terminal. Set it to
native to always use kitty’s native,
built-in askpass implementation. Note that not using the kitty askpass implementation
means that SSH might need to use the terminal before the connection is established
so the kitten cannot use the terminal to send data without an extra roundtrip,
adding to initial connection latency.
The copy command#
copy [options] file-or-dir-to-copy ...
Copy files and directories from local to remote hosts. The specified files are assumed to be relative to the HOME directory and copied to the HOME on the remote. Directories are copied recursively. If absolute paths are used, they are copied as is.
Interpret file arguments as glob patterns.
- --dest <DEST>#
The destination on the remote host to copy to. Relative paths are resolved relative to HOME on the remote host. When this option is not specified, the local file path is used as the remote destination (with the HOME directory getting automatically replaced by the remote HOME). Note that environment variables and ~ are not expanded.
- --exclude <EXCLUDE>#
A glob pattern. Files with names matching this pattern are excluded from being transferred. Useful when adding directories. Can be specified multiple times, if any of the patterns match the file will be excluded.