kurtosis-tech / 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 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: Finally, open the 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 or ) • [Messaging us on Twitter][twitter] Going further To try more Kurtosis packages just like this one, check out the [ 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 directory that give Claude operational knowledge about building, debugging, deploying, and managing Kurtosis enclaves. Available Skills | Skill | Description | |-------|-------------| | | Clean up enclaves and artifacts | | | Build the CLI from source | | | Manage Kurtosis clusters | | | Manage Kurtosis contexts | | | Debug Docker-based enclaves | | | Build and load Docker images locally | | | Dump enclave state for debugging | | | Inspect running enclaves | | | Start, stop, and restart the engine | | | Inspect files artifacts | | | Manage the Kurtosis gateway | | | Query Grafana and Loki observability | | | Import Docker Compose files | | | Clean Kurtosis resources from K8s | | | Debug pods on Kubernetes | | | Build and deploy dev images to K8s | | | Lint the codebase | | | Forward ports from enclaves | | | Manage the Kurtosis portal | | | Run Starlark packages | | | Manage services within enclaves | | | Develop Starlark packages | Installing Skills Skills are auto-discovered by Claude Code when present in a project's directory. There are several ways to install them: Option 1: Clone the repository (contributors) If you're contributing to Kurtosis, skills are already included: Claude Code will automatically discover the skills when you open a conversation in this directory. Option 2: Copy skills into your project Copy the directory into any project where you want Claude to have Kurtosis knowledge: Option 3: Symlink from another project If you want to keep skills in sync with the Kurtosis repo without copying: 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: Using Skills Once installed, skills are invoked as slash commands in Claude Code: You can also reference skills naturally in conversation — Claude will use the relevant skill context automatically when discussing Kurtosis topics. Contributing to Kurtosis ======================== Expand to see contribution info See our CONTRIBUTING file. Repository Structure -------------------- This repository is structured as a monorepo, containing the following projects: • : Library used to abstract away container engine being used by the [enclave][enclave]. • : Container launched inside an [enclave][enclave] to coordinate its state • : Container launched to coordinate [enclaves][enclave] • : Defines the API of the Kurtosis platform ( and ) • : Produces CLI binary, allowing interaction with the Kurtosis system • : Documentation that is published to docs.kurtosis.com • : End to end tests Dev Dependencies (Nix) ---------------- Install the Nix package manager. And enable some Nix flags (alternatively you can add eve…