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

# Core concepts

> Kisten and their names, the current selection, states, sizes, images, checkpoints, devices and credentials.

## Kiste

A Kiste is a cloud machine (a Firecracker microVM) with its own kernel,
memory and persistent disk, running Ubuntu 24.04 with a desktop. In the API it is called an
*instance*. The plural is *Kisten*.

Every Kiste has a **name** that is unique in your account. A name is 1 to 32
characters of lowercase letters, digits and hyphens, and does not start or end
with a hyphen; uppercase letters are lowercased for you. Without a name, Kiste
picks one such as `swift-otter-3fa2c1`. You can [rename](https://docs.kiste.run/kisten/manage.md#rename)
a Kiste later.

## The current Kiste

Most commands take a Kiste name, and most of them let you leave it out. The CLI
remembers a **current** Kiste: the one you created, resumed or forked last, or
the one you chose with `kiste current NAME`. A missing name means the current
Kiste.

```bash
kiste current            # print the current Kiste
kiste current review-42  # select another one
kiste current --clear    # forget the selection
```

The words `current` and `self` stand for the current Kiste wherever a name is
expected. Set `KISTE_CURRENT` to give one shell or one agent its own selection
without changing anyone else's:

```bash
export KISTE_CURRENT=build-7
kiste exec -- make test
```

## States

| State | Meaning |
| --- | --- |
| `starting` | Booting or resuming. |
| `running` | Reachable over SSH and accepting commands. |
| `stopping` | Shutting down, or saving its session. |
| `stopped` | Not running; its disk is kept and it uses no compute. When its session was saved, the next start resumes it. |
| `error` | It crashed or failed to start. Its disk is kept; start it again or read `kiste logs`. |

[Lifecycle](https://docs.kiste.run/kisten/lifecycle.md) explains each transition.

## Sizes

A Kiste has a number of vCPUs, an amount of memory and a disk size. Two presets
cover most work:

| Shape | vCPU | Memory | Disk |
| --- | --- | --- | --- |
| `default` | 4 | 8 GiB | 80 GiB |
| `large` | 8 | 16 GiB | 160 GiB |

Other combinations are possible within your account's limits; see
[Sizes and shapes](https://docs.kiste.run/kisten/create.md#sizes-and-shapes).

## Images and updates

Every Kiste starts from the **universal image**, which carries the whole
toolchain. The platform ships new image versions now and then; a running Kiste
never changes under you. `kiste list` and `kiste status` show when a newer
image is available, and `kiste update` moves a Kiste onto it with a reboot.
Files and installed packages stay. See [Update a Kiste](https://docs.kiste.run/kisten/manage.md#update).

## Sessions, checkpoints and snapshots

Three different things keep your work:

- **A saved session.** `kiste stop --snapshot` writes the Kiste's memory to its
  disk, so the next start resumes every process in about a second.
- **Automatic checkpoints.** Every Kiste's disk is checkpointed every five
  minutes when it changed, encrypted and copied off-site. You never have to
  trigger them. See [Checkpoints and snapshots](https://docs.kiste.run/kisten/snapshots.md).
- **Named snapshots.** A snapshot you take and name yourself, kept until you
  delete it. You can restore any snapshot or checkpoint as a new Kiste.

## Devices

Every computer you sign in on with `kiste login` gets its own SSH key, a
**device key**, and every Kiste of your account accepts all of them. Signing
out with `kiste logout` removes the computer's key again. `kiste devices` lists
them. See [Device keys](https://docs.kiste.run/ssh/devices.md).

## Sign-ins and API keys

There are three kinds of credentials:

- **Browser sessions**, when you sign in to the console at console.kiste.run.
- **CLI sign-ins**, created by `kiste login` and approved in the browser.
- **API keys** (`ksta_…`), labelled and expiring, for CI and automation. They
  can do almost everything a sign-in can; [API keys](https://docs.kiste.run/account/api-keys.md) lists
  the exceptions.

## Kiste Stream and desktop links

Two kinds of addresses share what runs in a Kiste:

- A **desktop link** opens the Kiste's desktop at desktop.kiste.run, and only
  for browsers signed in to your account.
- A **published port** on Kiste Stream gets its own public address under
  kiste.stream that anyone who knows it can open.

## Request IDs and error codes

Every request has a request ID, and every error a short code such as `K01`.
Quote both when you contact support. [Errors](https://docs.kiste.run/errors.md) lists every code.

## Related topics

- [What is Kiste](https://docs.kiste.run/get-started.md)
- [Quickstart](https://docs.kiste.run/get-started/quickstart.md)
- [Install the CLI](https://docs.kiste.run/get-started/install.md)
- [FAQ](https://docs.kiste.run/get-started/faq.md)
- Previous: [Install the CLI](https://docs.kiste.run/get-started/install.md)
- Next: [FAQ](https://docs.kiste.run/get-started/faq.md)