kurtosis

---

What is Kurtosis?

Have you ever tried to build on top of a colleague's work, or contribute to an open source project, just to get stuck on the first steps of spinning up a stack to play with? Kurtosis handles the complexity of spinning up ephemeral dev or test stacks so you can focus on developing, not configuring.

Kurtosis is formed of:

• A packaging system for distributing backend stack definitions, which can run on docker or on kubernetes
• A runtime with a per-stack file management system for reproducibly initializing the state of your stack
• A set of tools to enable devs to interact with their stacks, like they do on docker or k8s

Why use Kurtosis?

Kurtosis is best for:

• Reusing the logic in your stack definitions for all of: local dev, scheduled testing in CI, and ad-hoc larger-scale testing on k8s clusters
• Giving other devs a way to spin up your application, and commonly used variations of it, with one-liners, via Kurtosis' packaging and parameterization systems
• Handling complex setup logic in your backend stack, like passing arbitrary data between services as they start up, and enforcing arbitrary wait conditions

How is Kurtosis different than Docker Compose or Helm?

Kurtosis operates at a level higher than Docker Compose or Helm, and produces stacks running on either of the underlying engines (the Docker engine, or Kubernetes). Because of this additional layer of abstraction, we are able to introduce several features to improve the experience of spinning up ephemeral stacks:

• A per-stack file management system that enables portable state initialization for dev or test stacks
• Stack-level parameterizability; users have a powerful and flexible way (beyond messing with env vars) to affect modifications in their stacks
• First-class plug-and-play composability; it's expected for users to import stack definitions into larger stacks, and this experience is optimized
• The ability to get all of the above, but running over either the docker engine or k8s, at your election

NOTE: we do NOT recommend using Kurtosis to deploy long term production environments at this moment. Any issues/Discords related to production usage will be closed.

How do I get going?

To see Kurtosis in action, first install it using the instructions here.

Then, run the Redis voting app Kurtosis package:

kurtosis run github.com/kurtosis-tech/awesome-kurtosis/redis-voting-app

Finally, open the http link printed in the last line in your browser.

If you have an issue or feature request, we'd love to hear about it through one of the following:

• Post your question on our Github Discussions Forum
• [Asking for help on our Discord server][discord]
• Filing an issue on our Github (which can also be done via kurtosis feedback --bug or kurtosis feedback --feature)
• [Messaging us on Twitter][twitter]

Going further

To try more Kurtosis packages just like this one, check out the [awesome-kurtosis repo][awesome-kurtosis]!

To learn about how to write Kurtosis packages, check out our [quickstart][quickstart-reference].

To read about how Kurtosis works, see [our documentation][docs].

To see where we're going with the product, check out the roadmap here.

Got more questions? Drop them in our Github Discussions where we, or other community members, can help answer.

Claude Code Skills

This repository includes Claude Code skills that teach Claude how to work with Kurtosis. Skills are structured prompts in the skills/ directory that give Claude operational knowledge about building, debugging, deploying, and managing Kurtosis enclaves.

Available Skills

Skill	Description
clean	Clean up enclaves and artifacts
cli-local-build	Build the CLI from source
cluster-manage	Manage Kurtosis clusters
context-manage	Manage Kurtosis contexts
docker-debug	Debug Docker-based enclaves
docker-local-build	Build and load Docker images locally
dump	Dump enclave state for debugging
enclave-inspect	Inspect running enclaves
engine-manage	Start, stop, and restart the engine
files-inspect	Inspect files artifacts
gateway	Manage the Kurtosis gateway
grafloki	Query Grafana and Loki observability
import-compose	Import Docker Compose files
k8s-clean-cluster	Clean Kurtosis resources from K8s
k8s-debug-pods	Debug pods on Kubernetes
k8s-dev-deploy	Build and deploy dev images to K8s
lint	Lint the codebase
port-forward	Forward ports from enclaves
portal	Manage the Kurtosis portal
run-package	Run Starlark packages
service-manage	Manage services within enclaves
starlark-dev	Develop Starlark packages

Installing Skills

Skills are auto-discovered by Claude Code when present in a project's skills/ directory. There are several ways to install them:

Option 1: Clone the repository (contributors)

If you're contributing to Kurtosis, skills are already included:

git clone https://github.com/kurtosis-tech/kurtosis.git
cd kurtosis

Claude Code will automatically discover the skills when you open a conversation in this directory.

Option 2: Copy skills into your project

Copy the skills/ directory into any project where you want Claude to have Kurtosis knowledge:

# From the kurtosis repo, copy skills into your project
cp -r /path/to/kurtosis/skills /path/to/your-project/skills

Option 3: Symlink from another project

If you want to keep skills in sync with the Kurtosis repo without copying:

# Symlink the entire skills directory
ln -s /path/to/kurtosis/skills /path/to/your-project/skills

# Or symlink individual skills
mkdir -p /path/to/your-project/skills
ln -s /path/to/kurtosis/skills/run-package /path/to/your-project/skills/run-package

Option 4: Install globally for all projects

To make Kurtosis skills available across all your Claude Code projects, add them to your global Claude configuration:

# Copy skills to your global Claude config
cp -r /path/to/kurtosis/skills ~/.claude/skills

Using Skills

Once installed, skills are invoked as slash commands in Claude Code:

/clean          # Clean up enclaves
/run-package    # Run a Starlark package
/docker-debug   # Debug Docker containers
/k8s-debug-pods # Debug Kubernetes pods

You can also reference skills naturally in conversation — Claude will use the relevant skill context automatically when discussing Kurtosis topics.

Contributing to Kurtosis

See our CONTRIBUTING file.

Repository Structure

This repository is structured as a monorepo, containing the following projects:

• container-engine-lib: Library used to abstract away container engine being used by the [enclave][enclave].
• core: Container launched inside an [enclave][enclave] to coordinate its state
• engine: Container launched to coordinate [enclaves][enclave]
• api: Defines the API of the Kurtosis platform (engine and core)
• cli: Produces CLI binary, allowing interaction with the Kurtosis system
• docs: Documentation that is published to docs.kurtosis.com
• internal_testsuites: End to end tests

Dev Dependencies (Nix)

Install the Nix package manager.

sh <(curl -L https://nixos.org/nix/install)

And enable some Nix flags (alternatively you can add --extra-experimental-features 'nix-command flakes' every time calling the nix command):

mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

And to bring the environment up, just open a new shell terminal, go to the root folder of the repo and run:

nix  develop

This will download all dev deps and setup the environment accordingly.

You can also use the direnv to automatically load the environment when entering the main folder or using a plugin in your preferred IDE:

• vscode: mkhl.direnv
• jet brains: Direnv integration

Direnv can also be easily installed with Nix (or HomeBrew if you prefer):

nix-env -f '<nixpkgs>' -iA direnv

Now you just to add the direnv hook to your shell:

echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
# or for ZSH
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

Now next time you open a new shell terminal and go to repo's folder you environment will update and load automatically.

Dev Dependencies (Manual install)

The commands below assume that the env variable BREW_PREFIX contains the brew prefix.

BREW_PREFIX="$(brew --prefix)"

Bash (5 or above)

On MacOS:

# Install modern version of bash, the one that ships on MacOS is too old
brew install bash
# Allow bash as shell
echo "${BREW_PREFIX}/bin/bash" | sudo tee -a /etc/shells
# Optional: make bash your default shell
chsh -s "${BREW_PREFIX}/bin/bash"

Git

On MacOS:

# Install modern version of git, the one that ships on MacOS can be too old
brew install git

Docker

On MacOS:

brew install docker

Go (1.23 or above)

On MacOS:

brew install go@1.23
# Add the Go binary dir to your PATH
PATH="${BREW_PREFIX}/opt/go@1.23/bin:$PATH"
# Add the GOPATH bin dir to your PATH
PATH="${HOME}/go/bin:$PATH"

On Ubuntu:

wget https://go.dev/dl/go1.23.7.linux-amd64.tar.gz
tar -C /usr/local -zxf go1.23.7.linux-amd64.tar.gz
# Add the following to your bashrc or equivalent.
export PATH=$PATH:/usr/local/go/bin

Goreleaser

On MacOS:

brew install goreleaser/tap/goreleaser

On Ubuntu:

echo 'deb [trusted=yes] https://repo.goreleaser.com/apt/ /' | sudo tee /etc/apt/sources.list.d/goreleaser.list
sudo apt update
sudo apt install goreleaser

Node (20.* or above) and Yarn

On MacOS, using NVM:

brew install nvm
mkdir ~/.nvm
nvm install 20.11.0
npm install -g yarn

On Ubuntu, using NVM:

curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash
source ~/.bashrc
nvm install 20.11.0
npm install -g yarn

Rust

On MacOS, Ubuntu:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Go and Typescript protobuf compiler binaries

On MacOS:

brew install protoc-gen-go
brew install protoc-gen-go-grpc
go install connectrpc.com/connect/cmd/protoc-gen-connect-go@latest
yarn global add ts-protoc-gen
yarn global add grpc-tools

On Ubuntu: