> Documentation index: https://docs.kiste.run/llms.txt, a list of every page in this documentation.

# Overview

> Connect to a Kiste over SSH through kiste.run, without open ports, with pinned host keys and a shared connection.

```bash
kiste ssh                      # the current Kiste
kiste ssh review-42            # by name
kiste ssh review-42 -- uname -a   # run one command instead of a shell
```

`kiste shell` and `kiste terminal` are the same command. You log in as `root`.

## How the connection works

`kiste ssh` runs your own OpenSSH client. Its connection travels over HTTPS
to kiste.run and from there to the Kiste's SSH server, so:

- **no port is opened** on your network or on the Kiste, and nothing listens on
  the public internet for SSH;
- it works from wherever you can reach kiste.run, also behind strict firewalls
  and proxies that allow HTTPS;
- the Kiste's **host key is pinned**: the CLI fetches it over your signed-in
  connection and SSH refuses anything else, so there is no "unknown host"
  prompt to click through;
- only **your account's device keys** are accepted, password login is off.

The first `ssh`, `scp` or `forward` to a Kiste opens one **shared connection**
that stays for two minutes after its last use. Every further one within that
time skips the tunnel and the key exchange and starts instantly. (OpenSSH for
Windows has no connection sharing, so there each connection is set up anew.)

## Run a command

Anything after `--` runs as a remote command, with standard input forwarded:

```bash
kiste ssh review-42 -- tar czf - /workspace/results > results.tgz
kiste ssh review-42 -- 'cat >> notes.txt' < local-notes.txt
```

`kiste ssh` then exits with the remote command's status. Leading options after
`--` go to `ssh` itself:

```bash
kiste ssh review-42 -- -L 8080:localhost:8080
```

For scripts, `kiste exec` is usually better: it runs a program without a shell,
returns its exact output and status, and never needs a terminal. See
[Run commands](https://docs.kiste.run/ssh/commands.md).

## Print the ssh command

```bash
kiste ssh review-42 --print-command
```

prints the exact, safely quoted OpenSSH command line without connecting, for
tools that want to run `ssh` themselves.

## Plain ssh, scp and editors

Signing in sets up `NAME.kiste` as an SSH host on your computer, so plain
`ssh review-42.kiste`, `scp`, `rsync` and editors like VS Code work too. See
[SSH configuration and editors](https://docs.kiste.run/ssh/ssh-config.md).

## Limits

- An SSH connection closes after one hour without any traffic in either
  direction. The CLI sends keep-alives every 15 seconds while a session is
  open, so an interactive shell stays.
- An account can have 32 SSH connections open at once
  ([L12](https://docs.kiste.run/errors/l.md#l12)).
- Stopping, restarting or deleting the Kiste and signing out everywhere close
  its SSH connections.

## Errors you may see

| Code | Meaning |
| --- | --- |
| [K03](https://docs.kiste.run/errors/k.md#k03) | The Kiste isn't running. Start it with `kiste start NAME`. |
| [K04](https://docs.kiste.run/errors/k.md#k04) | The Kiste is still starting; its SSH server isn't listening yet. |
| [N08](https://docs.kiste.run/errors/n.md#n08) | The Kiste didn't accept this computer's key. Run `kiste login` on this computer. |
| [L12](https://docs.kiste.run/errors/l.md#l12) | Too many SSH connections are open. |

## Related topics

- [Copy files](https://docs.kiste.run/ssh/files.md)
- [Port forwarding](https://docs.kiste.run/ssh/forward.md)
- [SSH configuration and editors](https://docs.kiste.run/ssh/ssh-config.md)
- [Device keys](https://docs.kiste.run/ssh/devices.md)
- [Run commands](https://docs.kiste.run/ssh/commands.md)
- [Coding agents and credentials](https://docs.kiste.run/ssh/agents.md)
- [Browser terminal](https://docs.kiste.run/ssh/browser-terminal.md)
- Previous: [Connection](https://docs.kiste.run/desktop/connection.md)
- Next: [Copy files](https://docs.kiste.run/ssh/files.md)