.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "kitten-ssh" 1 "Oct 30, 2024" "0.37.0" "kitty"
.SH Name
kitten-ssh \- kitten Documentation
.SH Overview
.INDENT 0.0
.IP \(bu 2
Automatic \fI\%Shell integration\fP on remote hosts
.IP \(bu 2
Easily \fI\%clone local shell/editor config\fP on remote hosts
.IP \(bu 2
Automatic \fI\%re\-use of existing connections\fP to avoid connection setup latency
.IP \(bu 2
Make the kitten binary available in the remote host \fI\%on demand\fP
.IP \(bu 2
Easily \fI\%change terminal colors\fP when connecting to remote hosts
.IP \(bu 2
Automatically \fI\%forward the kitty remote control socket\fP to configured hosts
.UNINDENT
.sp
Added in version 0.25.0: Automatic shell integration, file transfer and reuse of connections

.sp
Added in version 0.30.0: Automatic forwarding of remote control sockets

.sp
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 \fI\%Shell integration\fP on the remote host and copies the
kitty terminfo database there.
.sp
The ssh kitten is a thin wrapper around the traditional \X'tty: link https://man.openbsd.org/ssh'\fI\%ssh\fP\X'tty: link'
command line program and supports all the same options and arguments and configuration.
In interactive usage scenarios it is a drop in replacement for \fBssh\fP\&.
To try it out, simply run:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
kitten ssh some\-hostname\-to\-connect\-to
.EE
.UNINDENT
.UNINDENT
.sp
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\(aqs rc files:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
alias s=\(dqkitten ssh\(dq
.EE
.UNINDENT
.UNINDENT
.sp
So now you can just type \fBs hostname\fP to connect.
.sp
If you define a mapping in \fBkitty.conf\fP such as:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
map f1 new_window_with_cwd
.EE
.UNINDENT
.UNINDENT
.sp
Then, pressing \fBF1\fP will open a new window automatically logged into the
same host using the ssh kitten, at the same directory.
.sp
The ssh kitten can be configured using the \fB~/.config/kitty/ssh.conf\fP 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\(aqs see a quick example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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.*
.EE
.UNINDENT
.UNINDENT
.sp
See below for full details on the syntax and options of \fBssh.conf\fP\&.
Additionally, you can pass config options on the command line:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
kitten ssh \-\-kitten interpreter=python servername
.EE
.UNINDENT
.UNINDENT
.sp
The \fB\-\-kitten\fP argument can be specified multiple times, with directives
from \fBssh.conf\fP\&. These override the final options used for the matched host, as if they
had been appended to the end of the matching section for that host in
\fBssh.conf\fP\&. They apply only to the host being SSHed to by this invocation,
so any \fI\%hostname\fP directives are ignored.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Due to limitations in the design of SSH, any typing you do before the
shell prompt appears may be lost. So ideally don\(aqt start typing till you see
the shell prompt. 😇
.UNINDENT
.UNINDENT
.SH A real world example
.sp
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\(aqt want to clobber their settings. Here is how
this could be achieved using the ssh kitten with \fBzsh\fP and
\fBvim\fP as the shell and editor, respectively:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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
.EE
.UNINDENT
.UNINDENT
.SH How it works
.sp
The ssh kitten works by having SSH transmit and execute a POSIX sh (or
\fI\%optionally\fP Python) bootstrap script on the
remote host using an \fI\%interpreter\fP\&. 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 \fI\%files\fP
and sets the \fI\%environment variables\fP before finally
launching the \fI\%login shell\fP with \fI\%shell
integration\fP 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 local
\X'tty: link https://www.openssh.com/'\fI\%OpenSSH\fP\X'tty: link' version is >= 8.4 then the data is
transmitted instantly without any roundtrip delay.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
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 \fBpython\fP as the
\fI\%interpreter\fP in \fBssh.conf\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This may or may not work when using terminal multiplexers, depending on
whether they passthrough the escape codes and if the values of the
environment variables \fI\%KITTY_PID\fP and \fI\%KITTY_WINDOW_ID\fP are
correct in the current session (they can be wrong when connecting to a tmux
session running in a different window) and the ssh kitten is run in the
currently active multiplexer window.
.UNINDENT
.UNINDENT
.SH Host bootstrap configuration
.INDENT 0.0
.TP
.B hostname
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
hostname *
.EE
.UNINDENT
.UNINDENT
.sp
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
\fBuser@host\fP\&. 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 \fI\%include\fP directive. In version 0.28.0
the behavior of this option was changed slightly, now, when a hostname is encountered
all its config values are set to defaults instead of being inherited from a previous
matching hostname block. In particular it means hostnames dont inherit configurations,
thereby avoiding hard to understand action\-at\-a\-distance.
.INDENT 0.0
.TP
.B interpreter
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
interpreter sh
.EE
.UNINDENT
.UNINDENT
.sp
The interpreter to use on the remote host. Must be either a POSIX complaint
shell or a \fBpython\fP executable. If the default \fBsh\fP is not
available or broken, using an alternate interpreter can be useful.
.INDENT 0.0
.TP
.B remote_dir
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
remote_dir .local/share/kitty\-ssh\-kitten
.EE
.UNINDENT
.UNINDENT
.sp
The location on the remote host where the files needed for this kitten are
installed. Relative paths are resolved with respect to \fB$HOME\fP\&. Absolute
paths have their leading / removed and so are also resolved with respect to $HOME.
.INDENT 0.0
.TP
.B copy
.UNINDENT
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
copy .vimrc .zshrc .config/some\-dir
.EE
.UNINDENT
.UNINDENT
.sp
Use \fB\-\-dest\fP to copy a file to some other destination on the remote host:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
copy \-\-dest some\-other\-name some\-file
.EE
.UNINDENT
.UNINDENT
.sp
Glob patterns can be specified to copy multiple files, with \fB\-\-glob\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
copy \-\-glob images/*.png
.EE
.UNINDENT
.UNINDENT
.sp
Files can be excluded when copying with \fB\-\-exclude\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
copy \-\-glob \-\-exclude *.jpg \-\-exclude *.bmp images/*
.EE
.UNINDENT
.UNINDENT
.sp
Files whose remote name matches the exclude pattern will not be copied.
For more details, see \fI\%The copy command\fP\&.
.SH Login shell environment
.INDENT 0.0
.TP
.B shell_integration
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
shell_integration inherited
.EE
.UNINDENT
.UNINDENT
.sp
Control the shell integration on the remote host. See \fI\%Shell integration\fP
for details on how this setting works. The special value \fBinherited\fP means
use the setting from \fBkitty.conf\fP\&. This setting is useful for overriding
integration on a per\-host basis.
.INDENT 0.0
.TP
.B login_shell
.UNINDENT
.sp
The login shell to execute on the remote host. By default, the remote user
account\(aqs login shell is used.
.INDENT 0.0
.TP
.B env
.UNINDENT
.sp
Specify the environment variables to be set on the remote host. Using the
name with an equal sign (e.g. \fBenv VAR=\fP) will set it to the empty string.
Specifying only the name (e.g. \fBenv VAR\fP) will remove the variable from
the remote shell environment. The special value \fB_kitty_copy_env_var_\fP
will cause the value of the variable to be copied from the local environment.
The definitions are processed alphabetically. Note that environment variables
are expanded recursively, for example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
env VAR1=a
env VAR2=${HOME}/${VAR1}/b
.EE
.UNINDENT
.UNINDENT
.sp
The value of \fBVAR2\fP will be \fB<path to home directory>/a/b\fP\&.
.INDENT 0.0
.TP
.B cwd
.UNINDENT
.sp
The working directory on the remote host to change to. Environment variables in
this value are expanded. The default is empty so no changing is done, which
usually means the HOME directory is used.
.INDENT 0.0
.TP
.B color_scheme
.UNINDENT
.sp
Specify a color scheme to use when connecting to the remote host. If this option
ends with \fB\&.conf\fP, 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 \fI\%themes kitten\fP\&. Note that
only colors applying to the text/background are changed, other config settings
in the .conf files/themes are ignored.
.INDENT 0.0
.TP
.B remote_kitty
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
remote_kitty if\-needed
.EE
.UNINDENT
.UNINDENT
.sp
Make \fBkitten\fP available on the remote host. Useful to run kittens such
as the \fI\%icat kitten\fP to display images or the
\fI\%transfer file kitten\fP to transfer files. Only works if
the remote host has an architecture for which \X'tty: link https://github.com/kovidgoyal/kitty/releases'\fI\%pre\-compiled kitten binaries\fP\X'tty: link' are available. Note that kitten
is not actually copied to the remote host, instead a small bootstrap script is
copied which will download and run kitten when kitten is first executed on the
remote host. A value of \fBif\-needed\fP means kitten is installed only if not
already present in the system\-wide PATH. A value of \fByes\fP means that kitten
is installed even if already present, and the installed kitten takes precedence.
Finally, \fBno\fP means no kitten is installed on the remote host. The
installed kitten can be updated by running: \fBkitten update\-self\fP on the
remote host.
.SH Ssh configuration
.INDENT 0.0
.TP
.B share_connections
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
share_connections yes
.EE
.UNINDENT
.UNINDENT
.sp
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.
You can map a shortcut to \fI\%close_shared_ssh_connections\fP to disconnect all
active shared connections.
.INDENT 0.0
.TP
.B askpass
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
askpass unless\-set
.EE
.UNINDENT
.UNINDENT
.sp
Control the program SSH uses to ask for passwords or confirmation of host keys
etc. The default is to use kitty\(aqs native \fBaskpass\fP, unless the
\fI\%SSH_ASKPASS\fP environment variable is set. Set this option to
\fBssh\fP to not interfere with the normal ssh askpass mechanism at all, which
typically means that ssh will prompt at the terminal. Set it to \fBnative\fP
to always use kitty\(aqs 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.
.INDENT 0.0
.TP
.B delegate
.UNINDENT
.sp
Do not use the SSH kitten for this host. Instead run the command specified as the delegate.
For example using \fBdelegate ssh\fP will run the ssh command with all arguments passed
to the kitten, except kitten specific ones. This is useful if some hosts are not capable
of supporting the ssh kitten.
.INDENT 0.0
.TP
.B forward_remote_control
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
forward_remote_control no
.EE
.UNINDENT
.UNINDENT
.sp
Forward the kitty remote control socket to the remote host. This allows using the kitty
remote control facilities from the remote host. WARNING: This allows any software
on the remote host full access to the local computer, so only do it for trusted remote hosts.
Note that this does not work with abstract UNIX sockets such as \fB@mykitty\fP because of SSH limitations.
This option uses SSH socket forwarding to forward the socket pointed to by the \fI\%KITTY_LISTEN_ON\fP
environment variable.
.SH The copy command
.INDENT 0.0
.INDENT 3.5
.sp
.EX
copy [options] file\-or\-dir\-to\-copy ...
.EE
.UNINDENT
.UNINDENT
.sp
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.
.SS Options
.INDENT 0.0
.TP
.B \-\-glob
Interpret file arguments as glob patterns. Globbing is based on standard wildcards with the addition that \fB/**/\fP matches any number of directories. See the \X'tty: link https://github.com/bmatcuk/doublestar#patterns'\fI\%detailed syntax\fP\X'tty: link'\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-exclude <EXCLUDE>
A glob pattern. Files with names matching this pattern are excluded from being transferred. Only used when copying directories. Can be specified multiple times, if any of the patterns match the file will be excluded. If the pattern includes a \fB/\fP then it will match against the full path, not just the filename. In such patterns you can use \fB/**/\fP to match zero or more directories. For example, to exclude a directory and everything under it use \fB**/directory_name\fP\&. See the \X'tty: link https://github.com/bmatcuk/doublestar#patterns'\fI\%detailed syntax\fP\X'tty: link' for how wildcards match.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-symlink\-strategy <SYMLINK_STRATEGY>
Control what happens if the specified path is a symlink. The default is to preserve the symlink, re\-creating it on the remote machine. Setting this to \fBresolve\fP will cause the symlink to be followed and its target used as the file/directory to copy. The value of \fBkeep\-path\fP is the same as \fBresolve\fP except that the remote file path is derived from the symlink\(aqs path instead of the path of the symlink\(aqs target. Note that this option does not apply to symlinks encountered while recursively copying directories, those are always preserved.
Default: \fBpreserve\fP
Choices: \fBkeep\-path\fP, \fBpreserve\fP, \fBresolve\fP
.UNINDENT
.SH Copying terminfo files manually
.sp
Sometimes, the ssh kitten can fail, or maybe you dont like to use it. In such
cases, the terminfo files can be copied over manually to a server with the
following one liner:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
infocmp \-a xterm\-kitty | ssh myserver tic \-x \-o \e~/.terminfo /dev/stdin
.EE
.UNINDENT
.UNINDENT
.sp
If you are behind a proxy (like Balabit) that prevents this, or you are SSHing
into macOS where the \fBtic\fP does not support reading from \fBSTDIN\fP,
you must redirect the first command to a file, copy that to the server and run \fBtic\fP
manually. If you connect to a server, embedded, or Android system that doesn\(aqt
have \fBtic\fP, copy over your local file terminfo to the other system as
\fB~/.terminfo/x/xterm\-kitty\fP\&.
.sp
If the server is running a relatively modern Linux distribution and you have
root access to it, you could simply install the \fBkitty\-terminfo\fP package on
the server to make the terminfo files available.
.sp
Really, the correct solution for this is to convince the OpenSSH maintainers to
have \fBssh\fP do this automatically, if possible, when connecting to a
server, so that all terminals work transparently.
.sp
If the server is running FreeBSD, or another system that relies on termcap
rather than terminfo, you will need to convert the terminfo file on your local
machine by running (on local machine with \fIkitty\fP):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
infocmp \-CrT0 xterm\-kitty
.EE
.UNINDENT
.UNINDENT
.sp
The output of this command is the termcap description, which should be appended
to \fB/usr/share/misc/termcap\fP on the remote server. Then run the following
command to apply your change (on the server):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
cap_mkdb /usr/share/misc/termcap
.EE
.UNINDENT
.UNINDENT
.SH Author

Kovid Goyal
.SH Copyright

2024, Kovid Goyal
.\" Generated by docutils manpage writer.
.