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 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.

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:

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 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.

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.

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.
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.

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 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 lists every code.

On this page