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

# Create a Kiste

> kiste new, names, sizes and shapes, lifetimes, checkpoint interval, images, environments and credentials.

```bash
kiste new
```

creates a Kiste with a generated name, the default size, and opens a shell in
it. `kiste start` and `kiste run` are the same command.

## What happens

1. Your [limits](https://docs.kiste.run/limits.md#account-limits) are checked and room is found for the
   new Kiste.
2. The Kiste boots from a copy-on-write clone of the universal image. It is
   ready when it accepts SSH and commands, usually within seconds. The desktop
   keeps starting in the background for a few more seconds.
3. The Kiste becomes your [current](https://docs.kiste.run/get-started/concepts.md#the-current-kiste)
   Kiste.
4. Unless you said otherwise, the CLI connects you to its shell.

Every Kiste accepts the SSH keys of all computers you signed in from, so you
can connect from any of them right away.

## Common forms

```bash
kiste new review-42                 # with a name
kiste new review-42 --no-ssh        # create and select, but stay in your shell
kiste new studio --desktop          # create and open the desktop in the browser
kiste new studio --desktop --no-open  # print the desktop link instead
kiste new build --shape large       # 8 vCPU, 16 GiB, 160 GiB
kiste new ci --ttl 1h --json        # unattended, stops by itself after an hour
```

When the name belongs to a Kiste that already exists, `kiste start NAME` brings
that one back instead of failing: a stopped Kiste is resumed, a running one is
connected to.

## Names

1 to 32 characters: lowercase letters, digits and hyphens, not starting or
ending with a hyphen. Uppercase letters are lowercased. Names are unique within
your account. Without a name, Kiste generates one such as `quiet-lynx-0a3f9e`.

## Sizes and shapes

| Option | Meaning |
| --- | --- |
| `--shape default` | 4 vCPU, 8 GiB memory, 80 GiB disk (also what you get without any option) |
| `--shape large` | 8 vCPU, 16 GiB memory, 160 GiB disk |
| `--cpu N` | Number of vCPUs |
| `--memory MIB` | Memory in MiB, such as `16384` |
| `--disk MIB` | Disk in MiB, such as `163840` |

`--shape` can't be combined with `--cpu`, `--memory` or `--disk`. The smallest
and largest values your account allows are shown by `kiste limits`. The size is
fixed at creation; to get a bigger Kiste, [fork](https://docs.kiste.run/kisten/fork.md) or
[restore](https://docs.kiste.run/kisten/snapshots.md#restore) into a new one, or create a new one.

## Lifetime

```bash
kiste new tmp --ttl 2h
```

`--ttl` gives the Kiste an automatic stop: in seconds, or with a unit such as
`90m`, `8h` or `7d`, from 60 seconds to 30 days. When the time is up, the
Kiste stops and keeps its disk; when the guest answers, its session is saved
so the next start resumes it. Without `--ttl` a Kiste runs until you stop it.
`kiste extend` pushes the stop further out; see
[Extend](https://docs.kiste.run/kisten/manage.md#extend).

## Checkpoint interval

Every Kiste is checkpointed automatically, by default every five minutes when
its disk changed. `--auto-snapshot` changes the interval, from 60 seconds to
one day (`30m`, `6h`, `1d`); checkpoints can't be switched off. See
[Checkpoints and snapshots](https://docs.kiste.run/kisten/snapshots.md).

## Image and environment

```bash
kiste new compiler --image "Rust work"
kiste new api-dev --environment backend
```

`--image` starts from one of your [custom images](https://docs.kiste.run/kisten/images.md#custom-images)
by ID, slug or name. `--environment` applies a [launch
environment](https://docs.kiste.run/kisten/images.md#environments): repositories to clone, variables,
secret files and a setup script.

## Credentials

```bash
kiste new agent-1 --auth
```

`--auth` carries the logins you selected with `kiste credentials` into the new
Kiste, such as `gh`, git, npm or a coding agent's login. Nothing is carried
without it. See [Coding agents and credentials](https://docs.kiste.run/ssh/agents.md).

## In the console

In the console, **Machines → New machine** asks for a name and a shape.

## Errors you may see

| Code | Meaning |
| --- | --- |
| [L02](https://docs.kiste.run/errors/l.md#l02) | Your account has as many Kisten as it may have. |
| [L03](https://docs.kiste.run/errors/l.md#l03) | Too many Kisten, vCPUs or memory are running at once. Stop one first. |
| [L04](https://docs.kiste.run/errors/l.md#l04) | Your Kisten and snapshots use all the disk your account may use. |
| [L13](https://docs.kiste.run/errors/l.md#l13) | There is no free capacity right now. Try again in a minute. |
| [K02](https://docs.kiste.run/errors/k.md#k02) | The name is already taken. |

## Related topics

- [Overview](https://docs.kiste.run/kisten.md)
- [Lifecycle](https://docs.kiste.run/kisten/lifecycle.md)
- [Checkpoints and snapshots](https://docs.kiste.run/kisten/snapshots.md)
- [Fork](https://docs.kiste.run/kisten/fork.md)
- [Manage](https://docs.kiste.run/kisten/manage.md)
- [Images and environments](https://docs.kiste.run/kisten/images.md)
- [Automation](https://docs.kiste.run/kisten/automation.md)
- Previous: [Overview](https://docs.kiste.run/kisten.md)
- Next: [Lifecycle](https://docs.kiste.run/kisten/lifecycle.md)