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

# Images and environments

> The universal image and its components, custom images, image versions, and immutable launch environments with repositories, variables, secret files and a setup script.

## The universal image

Every Kiste starts from one image, the **universal image** (`img_universal`,
slug `universal`): Ubuntu 24.04 LTS with GNOME and a complete toolchain. You
don't install the basics; they are there.

```bash
kiste image components      # every component with its exact version
kiste image list            # the universal image and your own images
```

| Component | What it contains |
| --- | --- |
| `git` | git |
| `curl` | curl |
| `javascript` | Node.js 24 with npm, pnpm, Bun and Deno |
| `python` | Python 3.12 with pip and uv |
| `native` | GCC, Clang, CMake, Ninja |
| `rust` | Rust with Clippy and rustfmt |
| `go` | Go |
| `jvm` | Java 21, Maven, Gradle, Kotlin, Scala, sbt |
| `ruby`, `php`, `dotnet`, `beam`, `r` | Ruby, PHP, .NET, Erlang and Elixir, R |
| `browser` | Firefox and Google Chrome |
| `media`, `desktop-tools`, `android` | Media, desktop and Android device tools |
| `docker` | Docker |
| `sqlite` | SQLite |
| `agents` | Codex and Claude Code |
| `jq`, `ripgrep` | jq, ripgrep |

`kiste image components` prints the exact versions of the current image.

## Image versions

Each image release has a version such as `v2026.10.06-0959cbf8`. A Kiste
records the version its disk last received; `kiste status` shows it, and
`kiste list` marks Kisten for which a newer one is available. Nothing changes
inside a running Kiste until you [update](https://docs.kiste.run/kisten/manage.md#update) it or it boots
fresh. Every image release is built from pinned, checksummed sources, scanned
for known vulnerabilities and reviewed before it is published.

## Custom images

A custom image is a saved selection of components with a default size. Because
every component is already part of the universal image, a custom image is ready
the moment you save it; it pins and checks the versions you depend on.

```bash
kiste image resolve --from universal --component rust=1.97.1
kiste image create "Rust work" --from universal --component rust=1.97.1
kiste image show "Rust work"
kiste new compiler --image "Rust work"
kiste image delete "Rust work" --yes
```

`resolve` shows what a selection would resolve to (exact versions, added
dependencies such as `native` for `rust`, recommended resources) without saving
it. `--cpu`, `--memory` and `--disk` set the image's default size. Images are
referenced by ID (`img_…`), slug or name. An image can't be deleted while a
Kiste uses it. The console lists images under **Images**.

## Environments

A launch environment prepares a new Kiste for one project: repositories to
clone, variables, secret files and a setup script. Environments are versioned
and immutable: every change publishes a new version, and a Kiste keeps the
version it was created with.

```bash
kiste environment create backend.json
kiste environment update backend backend.json
kiste environment list
kiste environment show backend
kiste new api-dev --environment backend
```

The manifest is a JSON file:

```json title="backend.json"
{
  "name": "backend",
  "repositories": [
    { "url": "https://github.com/example/api.git", "destination": "api", "revision": "main" }
  ],
  "variables": { "NODE_ENV": "development" },
  "secret_files": [
    { "path": "/home/kiste/.config/api/token", "contents_base64": "c2VjcmV0", "mode": 384 }
  ],
  "setup_script": "cd api && npm ci"
}
```

When a Kiste starts with an environment, a setup job runs in the background:

1. Each repository is cloned into `/workspace/<destination>` (by default the
   repository's name) and, with `revision`, checked out at that revision.
   Repository URLs must be absolute `https://` or `ssh://` URLs.
2. Each secret file is written to its path, which must be under `/home/kiste`,
   with its mode (a number; `384` is `0600`). Secret files are stored
   encrypted and are never shown again: the API lists only their paths.
3. The setup script runs in `/workspace` with the variables set.

`kiste status` shows the setup state; a failed setup raises a `setup_failed`
[alert](https://docs.kiste.run/account/webhooks-alerts.md) and the error stays visible only to you.

| Limit | Value |
| --- | --- |
| Repositories | 32 |
| Variables | 256 (names up to 256 bytes, values up to 64 KiB) |
| Secret files | 64 |
| Setup script | 256 KiB |
| Whole manifest | 512 KiB |

> **Info:** Private repositories
>
> Repositories are cloned before the secret files are written. For a private
> repository, write a deploy key or token as a secret file and clone it in the
> setup script, which runs last. `contents_base64` is URL-safe base64.

## Related topics

- [Overview](https://docs.kiste.run/kisten.md)
- [Create a Kiste](https://docs.kiste.run/kisten/create.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)
- [Automation](https://docs.kiste.run/kisten/automation.md)
- Previous: [Manage](https://docs.kiste.run/kisten/manage.md)
- Next: [Automation](https://docs.kiste.run/kisten/automation.md)