Install and run Kix

Install Kix with the install script, name the version of Kix your project uses, and verify that Kix can discover and evaluate your clusters.

Install with the install script

❱ curl -fsSL https://kix.run/install | sh

The script downloads the release archive for your platform (x86_64-linux, aarch64-linux, or aarch64-darwin) from kix.run and checks it against the release’s signed SHA256SUMS. It unpacks the archive to ~/.local/share/kix/<version>/ and links ~/.local/bin/kix to it. It never edits your shell startup files. If ~/.local/bin is not on your PATH, the script prints the line to add.

To install a specific version, set KIX_VERSION to an exact version:

❱ curl -fsSL https://kix.run/install | KIX_VERSION=0.8.3 sh

Variable	Default	Effect
KIX_VERSION	the latest release	The exact version to install, such as 0.8.3, or a prerelease such as 0.9.0-rc.1. A minor such as 0.8 matches no release. The latest release is never a prerelease.
KIX_INSTALL_DIR	~/.local/bin	The directory for the kix link.
XDG_DATA_HOME	~/.local/share	Kix versions are installed under $XDG_DATA_HOME/kix/.

The script stops without changing anything if ~/.local/bin/kix already exists and the script did not create it, for example a kix installed with Nix. Remove that file, or choose another directory with KIX_INSTALL_DIR.

Note

The script checks the Ed25519 signature of SHA256SUMS when the machine’s openssl can (OpenSSL 3 can, and the LibreSSL that ships with macOS cannot). When it cannot, the script says so and checks the SHA-256 of the release archive only. Kix itself always checks the signature when it installs another version.

Name the Kix version for a project

Set kix in kix.toml, beside flake.nix, so that everyone who works on the project, and every CI job, runs a matching version of Kix:

kix.toml

kix = "0.8"

kix = "0.8" accepts any 0.8 patch release, and Kix runs the newest 0.8 it has, the one you started or an installed one. kix = "0.8.3" accepts only 0.8.3. The setting must name Kix 0.8 or newer, because Kix 0.7 and older refuse a kix.toml that sets it. Commit kix.toml with git add kix.toml.

When you run kix in the project and the running Kix does not match, Kix runs a matching version from ~/.local/share/kix/ in its place, with the same arguments. When no matching version is installed, Kix downloads the newest matching release from kix.run, checks its signature and SHA-256, and then runs it:

Installing Kix 0.8.4 (this project needs 0.8)

To stop Kix from downloading versions, set KIX_AUTO_INSTALL=0. Kix then stops and names the command to run:

This project needs Kix 0.8 (kix.toml), and no Kix 0.8 is installed. Automatic installs are off (KIX_AUTO_INSTALL=0). Run `kix self install 0.8`.

kix --version and kix doctor report which Kix chose the running one and for which kix.toml. kix --version never downloads a version. When the project’s version is not installed, it says so and leaves the install to the next kix command.

Manage installed versions

kix self installs, lists, and removes versions of Kix:

❱ kix self list

❱ kix self install 0.8

❱ kix self prune

❱ kix self update

kix self update installs the latest release and moves the kix link the install script made to it, when the install script installed the running Kix.

When Kix and the Kix library do not match

The Kix library that your project pins in flake.lock has a version too. Kix builds a project only when the Kix library has the same minor version as Kix and a patch version no newer than Kix’s. Otherwise Kix stops before it evaluates and names the fix. For example, when Kix is newer than the Kix library:

This project's Kix library is 0.8.0, but this is Kix 0.9.1. Run `kix lib update` to move the project to the 0.9.1 library and commit flake.lock. To keep this project on Kix 0.8 instead, set kix = "0.8" in kix.toml.

Run kix lib update to move the project to the Kix library of the running Kix. To keep the Kix library, set kix in kix.toml to the Kix library’s minor, and Kix runs that version for the project. Installing a version with kix self install alone does not change which Kix runs, because Kix chooses a version only from kix.toml.

When the Kix library is a newer patch of the running Kix’s minor, such as library 0.8.3 and Kix 0.8.1, run kix self install 0.8. With kix = "0.8" in kix.toml, Kix then runs the new patch for this project. Without a kix setting, run kix self update to move the kix on your PATH.

Verify the installation

Check the installed version:

❱ kix --version
kix 0.9.2

Verify that Kix and its runtime tools are healthy:

❱ kix doctor

Confirm that the command list is available:

❱ kix --help

Run your first command

Kix evaluates the project in the current directory unless you pass --flake. From a Kix project, list the clusters it defines:

kix-examples/

❱ kix list clusters

If the project is in another directory, pass --flake:

❱ kix --flake /path/to/project list clusters

By default (builder = "kix"), Kix evaluates with the Kix runtime and downloads the project’s locked inputs into Kix’s local store (~/.cache/kix/store, or $XDG_CACHE_HOME/kix/store). Later commands reuse the cached inputs. Set KIX_STORE_ROOT if you want Kix to keep its local store in a different directory. A project can instead use the Nix already installed on the machine. See kix.toml.

Install from a release archive

Where you cannot run the install script, such as in a container image build, download a release archive yourself. Replace 0.8.4 with the version you want, and x86_64-linux with aarch64-linux on ARM64 Linux or aarch64-darwin on Apple silicon macOS:

❱ curl -fsSLO https://kix.run/download/0.8.4/kix-x86_64-linux.tar.gz

❱ curl -fsSL https://kix.run/releases/v0.8.4/SHA256SUMS | grep ' kix-x86_64-linux.tar.gz$' | sha256sum -c -

❱ mkdir -p ~/.local

❱ tar -xzf kix-x86_64-linux.tar.gz --strip-components=1 -C ~/.local

On macOS, check the archive with shasum -a 256 -c - in place of sha256sum -c -. Make sure ~/.local/bin is on your PATH.

Note

The archive unpacks bin/kix alongside its runtime tools in libexec/kix/. Keep both directories in the same parent directory (or symlink ~/.local/bin/kix to the unpacked bin/kix). If you move libexec/kix/ somewhere else, set KIX_RUNTIME_DIR to its path.

kix self update does not update a Kix installed this way. A project that sets kix in kix.toml still gets its matching version, which Kix installs under ~/.local/share/kix/.

Install with Nix

If you manage tools with Nix flakes and have access to the Kix repository, which is not public yet, you can install Kix from its flake:

❱ nix profile install github:kix-run/kix#kix

Upgrade it with nix profile upgrade kix. kix self update prints that command instead of upgrading a Kix installed this way.

Reference

See kix self for managing installed versions, kix doctor for how Kix verifies its runtime directory and project builder, kix.toml for the kix and builder settings, and Global flags for shared CLI flags and environment variables.

Try it as a tutorial

Work through local setup and your first Kix deployment to create a kind cluster and run the complete edit, check, deploy, and verify loop.