Images and environments

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.

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

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

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.

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:

{
  "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 and the error stays visible only to you.